Method: customers.uploadClickConversions

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

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

طلب HTTP

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

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

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

المعلمات
customerId

string

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

نص الطلب

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

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

object (ClickConversion)

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

boolean

مطلوب. إذا كانت القيمة صحيحة، سيتم تنفيذ العمليات الناجحة وستعرض العمليات غير الصالحة أخطاءً. إذا كانت القيمة "false"، سيتم تنفيذ جميع العمليات في معاملة واحدة فقط إذا كانت جميعها صالحة. يجب ضبطها دائمًا على true. راجِع 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". وسيتيح لك ذلك التركيز فقط على الأخطاء التي يمكنك معالجتها.

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

integer

اختياريّ. إدخال اختياري لضبط معرّف الوظيفة. يجب أن يكون رقمًا غير سالب أقل من 2^31 إذا تم تقديمه. في حال عدم توفير هذا الحقل، ستنشئ واجهة برمجة التطبيقات معرّف وظيفة في النطاق [2^31, (2^63)-1]. ستعرض واجهة برمجة التطبيقات قيمة هذا الطلب في الحقل jobId من UploadClickConversionsResponse.

نص الاستجابة

رسالة ردّ على 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)

يتمّ عرضها للإحالات الناجحة التي تمّت معالجتها بنجاح. سيكون النموذج الأوّلي فارغًا للصفوف التي حصلت على خطأ. لا يتم عرض النتائج عندما يكون التحقق من الصحة فقط صحيحًا.
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),
  "consent": {
    object (Consent)
  },
  "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)

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

object (Consent)

إعداد الموافقة الخاص بالحدث
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. على سبيل المثال: USD أو 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

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

object (Item)

بيانات السلع المشتراة

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

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

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

string

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

integer

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

number

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

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".