Method: customers.uploadClickConversions

معالجة الإحالات الناجحة الناتجة عن النقرات المحدّدة.

قائمة الأخطاء التي تظهر: AuthenticationError AuthorizationError ConversionUploadError HeaderError InternalError PartialFailureError QuotaError RequestError

طلب HTTP

POST https://googleads.googleapis.com/v14/customers/{customerId}:uploadClickConversions

يستخدِم عنوان URL بنية تحويل ترميز gRPC.

مَعلمات المسار

المَعلمات
customerId

string

مطلوبة. رقم تعريف العميل الذي يُجري عملية التحميل

نص الطلب

يحتوي نص الطلب على بيانات بالبنية التالية:

تمثيل JSON 
{
  "conversions": [
    {
      object (ClickConversion)
    }
  ],
  "partialFailure": boolean,
  "validateOnly": boolean,
  "debugEnabled": boolean
}
الحقول
conversions[]

object (ClickConversion)

مطلوبة. الإحالات الناجحة التي يتم تحميلها.
partialFailure

boolean

مطلوبة. في حال ضبط هذه السياسة على "صحيح"، سيتم تنفيذ عمليات ناجحة، وستعرض العمليات غير الصالحة أخطاء. وفي حال اختيار القيمة "false"، سيتم تنفيذ جميع العمليات في معاملة واحدة فقط إذا كانت كلها صالحة. يجب ضبط هذه السياسة دائمًا على "صحيح". يمكنك الانتقال إلى https://developers.google.com/google-ads/api/docs/best-practices/partial-failures للحصول على مزيد من المعلومات عن الفشل الجزئي.
validateOnly

boolean

إذا كانت القيمة true، يتم التحقق من صحة الطلب ولكن لا يتم تنفيذه. يتم عرض الأخطاء فقط وليس النتائج.
debugEnabled

boolean

في حال ضبط هذه السياسة على "صحيح"، ستجري واجهة برمجة التطبيقات كل عمليات التحقّق من التحميل وتعرض أخطاءً في حال العثور على أي أخطاء. أمّا إذا كانت القيمة "خطأ"، فستجري فقط التحقّق من الإدخال الأساسي، وتتخطّى عمليات التحميل اللاحقة، وتعرض نجاح العملية حتى في حال عدم العثور على أي نقرة على عنصر userIdentifiers المقدّم.

لا يؤثّر هذا الإعداد إلّا في الإحالات الناجحة المحسّنة للعملاء المحتملين الذين يستخدِمون userIdentifiers بدلاً من GCLID أو GBRAID أو WBRAID. عند تحميل الإحالات الناجحة المحسّنة للعملاء المحتملين، عليك تحميل جميع أحداث الإحالات الناجحة إلى واجهة برمجة التطبيقات، بما في ذلك الأحداث التي قد لا تكون واردة من الحملات على "إعلانات Google". سيؤدي تحميل حدث ليس من حملة على "إعلانات Google" إلى خطأ CLICK_NOT_FOUND في حال ضبط هذا الحقل على true. بما أنّه من المتوقّع حدوث هذه الأخطاء مع مثل هذه الأحداث، اضبط هذا الحقل على false حتى تتمكّن من التأكّد من تنسيق عمليات التحميل بشكلٍ سليم مع تجاهل أخطاء CLICK_NOT_FOUND من جميع الإحالات الناجحة التي لا تأتي من حملة على "إعلانات Google". وسيتيح لك هذا التركيز فقط على الأخطاء التي يمكنك معالجتها.

القيمة التلقائية هي "خطأ".

نص الاستجابة

رسالة الرد على ConversionUploadService.UploadClickConversions.

إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:

تمثيل JSON 
{
  "partialFailureError": {
    object (Status)
  },
  "results": [
    {
      object (ClickConversionResult)
    }
  ],
  "jobId": string
}
الحقول
partialFailureError

object (Status)

الأخطاء التي تتعلّق بحالات تعذُّر الإحالات الناجحة في وضع الفشل الجزئي. يتم عرضه عند حدوث جميع الأخطاء داخل الإحالات الناجحة. وفي حال حدوث أي أخطاء خارج الإحالات الناجحة (على سبيل المثال، أخطاء في المصادقة)، يتمّ عرض خطأ على مستوى استدعاء إجراء عن بُعد (RPC). يمكنك الانتقال إلى https://developers.google.com/google-ads/api/docs/best-practices/partial-failures للحصول على مزيد من المعلومات عن الفشل الجزئي.
results[]

object (ClickConversionResult)

يُعرَض بسبب الإحالات الناجحة التي تمت معالجتها بنجاح. سيكون Proto فارغًا للصفوف التي تتلقى خطأ. لا يتم عرض النتائج عندما تكون قيمة annotate Only صحيحة.
jobId

string (int64 format)

معرّف المهمة لدُفعة التحميل

نطاقات التفويض

يجب توفير نطاق OAuth التالي:

  • https://www.googleapis.com/auth/adwords

لمزيد من المعلومات، راجِع نظرة عامة على بروتوكول OAuth 2.0.

ClickConversion

إحالة ناجحة ناتجة عن نقرة.

تمثيل JSON 
{
  "gbraid": string,
  "wbraid": string,
  "externalAttributionData": {
    object (ExternalAttributionData)
  },
  "customVariables": [
    {
      object (CustomVariable)
    }
  ],
  "cartData": {
    object (CartData)
  },
  "userIdentifiers": [
    {
      object (UserIdentifier)
    }
  ],
  "conversionEnvironment": enum (ConversionEnvironment),
  "gclid": string,
  "conversionAction": string,
  "conversionDateTime": string,
  "conversionValue": number,
  "currencyCode": string,
  "orderId": string
}
الحقول
gbraid

string

معرّف النقرة للنقرات المرتبطة بالإحالات الناجحة للتطبيق والتي تنشأ من أجهزة iOS بدءًا من نظام التشغيل iOS14.
wbraid

string

معرّف النقرة للنقرات المرتبطة بالإحالات الناجحة على الموقع الإلكتروني والتي تنشأ من أجهزة iOS بدءًا من نظام التشغيل iOS14
externalAttributionData

object (ExternalAttributionData)

بيانات إضافية عن الإحالات الناجحة المنسوبة خارجيًا هذا الحقل مطلوب للإحالات الناجحة التي تتضمّن إجراء إحالة ناجحة منسوبًا إلى جهة خارجية، ولكن يجب عدم إعداده على خلاف ذلك.
customVariables[]

object (CustomVariable)

المتغيّرات المخصّصة المرتبطة بهذه الإحالة الناجحة.
cartData

object (CartData)

بيانات سلة التسوّق المرتبطة بهذه الإحالة الناجحة.
userIdentifiers[]

object (UserIdentifier)

أرقام تعريف المستخدمين المرتبطة بهذه الإحالة الناجحة. لا تتوفّر عمليات تحميل الإحالات الناجحة إلّا المجزَّأ ورقم الهاتف المجزأ. الحد الأقصى لعدد معرّفات المستخدمين لكل إحالة ناجحة هو 5.
conversionEnvironment

enum (ConversionEnvironment)

البيئة التي تم تسجيل هذه الإحالة الناجحة فيها، مثل التطبيق أو الويب.
gclid

string

معرّف النقرة من Google (gclid) المرتبط بهذه الإحالة الناجحة.
conversionAction

string

اسم المورد لإجراء الإحالة الناجحة المرتبط بهذه الإحالة الناجحة. ملاحظة: على الرغم من أنّ اسم المورد هذا يتألف من رقم تعريفي للعميل ومعرّف إجراء إحالة ناجحة، ستتجاهل عملية التحقّق الرقم التعريفي للعميل واستخدام معرّف إجراء الإحالة الناجحة كمعرّف إجراء الإحالة الناجحة الوحيد.
conversionDateTime

string

التاريخ الذي حدثت فيه الإحالة الناجحة. يجب أن يكون بعد وقت النقرة. يجب تحديد المنطقة الزمنية. التنسيق هو "yyyy-mm-dd hh:mm:ss+|-hh:mm"، على سبيل المثال، "2019-01-01 12:32:45-08:00".
conversionValue

number

قيمة الإحالة الناجحة للمعلِن.
currencyCode

string

العملة المرتبطة بقيمة الإحالة الناجحة. هذا هو رمز العملة المكوّن من 3 أحرف بتنسيق ISO 4217. على سبيل المثال: SAR أو EUR.
orderId

string

مُعرّف الطلب المرتبط بالإحالة الناجحة. لا يمكن استخدام مُعرّف الطلب إلا لإحالة ناجحة واحدة لكل إجراء إحالة ناجحة.

ExternalAttributionData

يحتوي على معلومات إضافية عن الإحالات الناجحة المنسوبة خارجيًا.

تمثيل JSON 
{
  "externalAttributionCredit": number,
  "externalAttributionModel": string
}
الحقول
externalAttributionCredit

number

يمثل نسبة الإحالة الناجحة المنسوبة إلى نقرة "إعلانات Google".
externalAttributionModel

string

تُحدِّد اسم نموذج تحديد المصدر.

CartData

يحتوي على معلومات إضافية حول بيانات سلة التسوّق.

تمثيل JSON 
{
  "merchantId": string,
  "feedCountryCode": string,
  "feedLanguageCode": string,
  "localTransactionCost": number,
  "items": [
    {
      object (Item)
    }
  ]
}
الحقول
merchantId

string (int64 format)

معرّف Merchant Center الذي تمّ تحميل السلع فيه.
feedCountryCode

string

رمز البلد المرتبط بالخلاصة التي يتمّ تحميل السلع فيها.
feedLanguageCode

string

رمز اللغة المرتبط بالخلاصة التي تمّ تحميل السلع فيها.
localTransactionCost

number

مجموع كلّ الخصومات على مستوى المُعاملة، مثل الشحن المجاني وخصومات القسائم لسلة التسوّق بالكامل. ويكون رمز العملة هو نفسه الرمز الوارد في رسالة Clickconversion.
items[]

object (Item)

بيانات السلع التي تمّ شراؤها

المنتج/الخدمة

يحتوي على بيانات السلع التي تم شراؤها.

تمثيل JSON 
{
  "productId": string,
  "quantity": integer,
  "unitPrice": number
}
الحقول
productId

string

معرّف التسوّق للسلعة. يجب أن تكون القيمة مساوية لمعرّف المنتج في Merchant Center.
quantity

integer

عدد السلع المُباعة.
unitPrice

number

سعر الوحدة غير شامل للضرائب أو تكاليف الشحن أو أيّ خصومات على مستوى المُعاملة. ويكون رمز العملة هو نفسه الرمز الوارد في رسالة Clickconversion.

ConversionEnvironment

بيئة الإحالة الناجحة للإحالة الناجحة التي تم تحميلها.

عمليات التعداد
UNSPECIFIED غير محدَّد.
UNKNOWN يُستخدم للقيمة المعروضة فقط. يعرض قيمة غير معروفة في هذا الإصدار.
APP تم تسجيل الإحالة الناجحة في أحد التطبيقات.
WEB تم تسجيل الإحالة الناجحة على موقع إلكتروني.

ClickConversionResult

تحديد معلومات إحالة ناجحة ناتجة عن النقر تمت معالجتها بنجاح.

تمثيل JSON 
{
  "gbraid": string,
  "wbraid": string,
  "userIdentifiers": [
    {
      object (UserIdentifier)
    }
  ],
  "gclid": string,
  "conversionAction": string,
  "conversionDateTime": string
}
الحقول
gbraid

string

معرّف النقرة للنقرات المرتبطة بالإحالات الناجحة للتطبيق والتي تنشأ من أجهزة iOS بدءًا من نظام التشغيل iOS14.
wbraid

string

معرّف النقرة للنقرات المرتبطة بالإحالات الناجحة على الموقع الإلكتروني والتي تنشأ من أجهزة iOS بدءًا من نظام التشغيل iOS14
userIdentifiers[]

object (UserIdentifier)

أرقام تعريف المستخدمين المرتبطة بهذه الإحالة الناجحة. لا تتوفّر عمليات تحميل الإحالات الناجحة إلّا المجزَّأ ورقم الهاتف المجزأ. الحد الأقصى لعدد معرّفات المستخدمين لكل إحالة ناجحة هو 5.
gclid

string

معرّف النقرة من Google (gclid) المرتبط بهذه الإحالة الناجحة.
conversionAction

string

اسم المورد لإجراء الإحالة الناجحة المرتبط بهذه الإحالة الناجحة.
conversionDateTime

string

التاريخ الذي حدثت فيه الإحالة الناجحة. التنسيق هو "yyyy-mm-dd hh:mm:ss+|-hh:mm"، على سبيل المثال، "2019-01-01 12:32:45-08:00".