استخدِم طريقة Conversion.update() لإجراء الأنواع التالية من التغييرات على إحالة ناجحة حالية واحدة أو أكثر:
- عدِّل الإيرادات أو رمز العملة أو الكمية.
- عدِّل معرّف الطلب الذي يقدّمه المعلِن وأي متغيّرات Floodlight مخصّصة.
- أزِل الإحالة الناجحة عن طريق تغيير
conversion.stateمنACTIVEإلىREMOVED.
لا تتيح "إعلانات شبكة البحث 360" تغيير ما يلي:
- تاريخ الإحالة الناجحة
- نوع الإحالة الناجحة
- الكلمة الرئيسية أو الزيارة المنسوبة إلى الإحالة الناجحة
- نشاط Floodlight أو اسم النشاط
ومع ذلك، يمكنك دائمًا وضع علامة "تمت الإزالة" على إحالة ناجحة حالية وتحميل إحالة ناجحة جديدة
بالتاريخ أو النوع أو معرّفات تحديد المصدر أو نشاط Floodlight المعدَّل (تأكَّد من تحديد
conversionId جديد أيضًا).
يمكنك تعديل كلّ من الإحالات الناجحة التي تم تحميلها من خلال Search Ads 360 API (الإحالات الناجحة غير الإلكترونية) والإحالات الناجحة التي سجّلتها "إعلانات شبكة البحث 360" من خلال علامات Floodlight (الإحالات الناجحة الإلكترونية)، وذلك وفقًا للمُدد الزمنية التالية:
-
إذا حدّدت الإحالة الناجحة باستخدام
clickId، يجب أن يكون معرّف النقرة قد تم إنشاؤه خلال آخر 60 يومًا (وإلا سيظهر رمز الخطأ0x0000012F). -
لا يمكن تعديل الإحالات الناجحة المسجّلة من خلال علامات Floodlight إلّا خلال 28 يومًا من
conversionTimestamp(رمز الخطأ0x00000125في الحالات الأخرى).
كما هو الحال مع Conversion.insert()، إذا كان طلب التعديل يحدّد إحالات ناجحة متعددة، تحاول "إعلانات شبكة البحث 360" تعديل كل إحالة ناجحة على أساس بذل قصارى جهدها بدلاً من تعديل الدفعة بأكملها كمعاملة "الكل أو لا شيء". إذا تعذّر إجراء بعض التعديلات في دفعة معيّنة، قد تنجح التعديلات الأخرى. ننصحك بقراءة الردّ لكل إحالة ناجحة تم تعديلها للتأكّد من نجاح التعديل.
إيقاف نهائي لـ dsConversionId
تم إيقاف الحقل dsConversionId نهائيًا ولم يعُد بالإمكان استخدامه لتحديد الإحالات الناجحة. يجب استخدام conversionId (رقم تعريف الإحالة الناجحة للمعلِن) لتعديل
الإحالات الناجحة في Search Ads 360 Conversion API. يرفض Conversion.update()
الإحالة الناجحة مع رمز الخطأ 0x0000013C (Conversion editing using
integer DS conversion ID is deprecated) إذا كانت الإحالة الناجحة:
- يحدّد حقل
dsConversionId، أو - تمرير رقم تعريف الإحالة الناجحة في "إعلانات شبكة البحث 360" (رقم التعريف الرقمي المكوّن من 17 رقمًا والذي تنشئه "إعلانات شبكة البحث 360" لكل إحالة ناجحة) في الحقل
conversionId.
أهم التغييرات:
-
إيقاف
dsConversionIdنهائيًا:dsConversionIDلم يعُد متاحًا في Search Ads 360 Conversion API وSearch Ads 360 Reporting API (يُشار إليه باسمconversion.id) وواجهة مستخدم إعداد التقارير (يُشار إليه باسم "رقم تعريف الإحالة الناجحة"). -
conversionIdالمتطلّب:conversionIdهو حقل مطلوب لتعديل الإحالات الناجحة من خلال Search Ads 360 Conversion API.
كيفية الحصول على conversionId:
-
الإحالات الناجحة التي تم تحميلها من خلال Search Ads 360 API: استخدِم
conversionIdالذي حدّدته عند إدراج الإحالة الناجحة. -
الإحالات الناجحة المسجَّلة من خلال علامات Floodlight: استخدِم معرّف طلب Floodlight (القيمة
ord) الذي أبلغت عنه علامة Floodlight للإحالة الناجحة، مثل معرّف الطلب أو معرِّف المعاملة لنشاط مبيعات Floodlight. -
Search Ads 360 Reporting API: يمكنك استرداد
advertiser_conversion_idباستخدام Search Ads 360 Reporting API. تتوافق هذه القيمة مع السمةconversionIdالمطلوبة للتعديل. -
واجهة مستخدم "إعلانات شبكة البحث 360": يمكنك العثور على "رقم تعريف الإحالة الناجحة للمعلِن" في صفحة تقارير الإحالات الناجحة ضمن واجهة مستخدم "إعلانات شبكة البحث 360".
إرسال طلب تعديل
تُستخدم معظم الحقول التي تحدّدها في Conversion.update() لتحديد الإحالات الناجحة التي تريد تعديلها. يمكنك استخدام أيٍّ من الأساليب التالية لتحديد إحالة ناجحة حالية:
- حدِّد
clickIdللإحالة الناجحة.- يجب أن تكون جميع الإحالات الناجحة التي تم تعديلها خلال 60 يومًا من وقت إنشاء معرّف النقرة.
- حدِّد الكلمة الرئيسية للإحالة الناجحة (
customerIdوcampaignIdوadGroupIdوcriterionId)
تتطلّب كلتا الطريقتَين تحديد conversionId وconversionTimestamp للإحالة الناجحة،
وtype للمعاملة. يجب أن يكون conversionTimestamp هو الطابع الزمني للإحالة الناجحة الحالية، بالملي ثانية حسب التوقيت العالمي المنسَّق (UTC). إذا لم يتطابق الطابع الزمني مع الإحالة الناجحة الحالية (على سبيل المثال، لأنّه تم تحويله من منطقة زمنية محلية)، لن تتمكّن "إعلانات شبكة البحث 360" من العثور على الإحالة الناجحة وستعرض رمز الخطأ 0x0000011B.
بالنسبة إلى الإحالات الناجحة التي سجّلتها "إعلانات شبكة البحث 360" من خلال علامات Floodlight، عليك أيضًا
تحديد نشاط Floodlight للإحالة الناجحة (segmentationType
وإما segmentationName أو segmentationId). وإلا،
سيتعذّر تنفيذ الطلب وسيظهر رمز الخطأ 0x0000010C. ننصحك بتحديد نشاط Floodlight في كل طلب تعديل.
بالإضافة إلى ذلك، إذا كانت الإحالة الناجحة الأصلية تحدّد revenueMicros وcurrencyCode أو quantityMillis، يجب أن يحدّد طلب التعديل هذه البيانات حتى إذا لم تكن بصدد تغييرها.
تحديد الإحالة الناجحة حسب معرّف النقرة
إذا كانت الإحالة الناجحة قد حدّدت في الأصل معرّف نقرة، يمكنك إرسال طلب Conversion.update()
يحدّد الحقول التالية:
clickIdconversionIdconversionTimestamptype-
segmentationTypeوsegmentationName(أوsegmentationId) (مطلوبتان للإحالات الناجحة المسجّلة من خلال علامات Floodlight، ويُنصح باستخدامهما لجميع الإحالات الناجحة) -
state(مطلوب فقط إذا أردت تغيير الحالة إلى "تمت الإزالة" أو "نشط") -
quantityMillis(فقط في حال تحديدها في الإحالة الناجحة الأصلية) -
revenueMicros(فقط في حال تحديدها في الإحالة الناجحة الأصلية) -
currencyCode(فقط في حال تحديدها في الإحالة الناجحة الأصلية)
مثال
في ما يلي مثال على إحالتَين ناجحتَين حاليتَين:
{ "kind": "doubleclicksearch#conversionList", "conversion" : [{ "clickId" : "COiYmPDTv7kCFcP0KgodOzQAAA", "conversionId" : "test_20130906_10", "conversionTimestamp" : "1378710000000", "segmentationType" : "FLOODLIGHT", "segmentationName" : "Test", "type": "TRANSACTION", "revenueMicros": "100000000", // 100 million revenueMicros is equivalent to $100 of revenue "currencyCode": "USD" }, { "clickId": "COiYmPDTv7kCFcP0KgodOzQAAA", "conversionId": "test_1383337059137", "conversionTimestamp": "1378710000000", "segmentationType" : "FLOODLIGHT", "segmentationName" : "Test", "type": "ACTION", "quantityMillis": "1000" }] }
يعدّل الطلب التالي إحدى الإحالات الناجحة من المثال السابق ويزيل الأخرى:
JSON
يُرجى العِلم أنّ طلب Conversion.update() يستخدم طريقة HTTP PUT.
PUT https://www.googleapis.com/doubleclicksearch/v2/conversion Authorization: Bearer your OAuth 2.0 access token Content-type: application/json { "kind": "doubleclicksearch#conversionList", "conversion": [ { "clickId": "COiYmPDTv7kCFcP0KgodOzQAAA", // Replace with data from your site "conversionId": "test_20130906_10", "conversionTimestamp": "1378710000000", "segmentationType" : "FLOODLIGHT", "segmentationName" : "Test", "type": "TRANSACTION", "revenueMicros": "90000000", // 90 million revenueMicros is equivalent to $90 of revenue "currencyCode": "USD" }, { "clickId": "COiYmPDTv7kCFcP0KgodOzQAAA", // Replace with data from your site "conversionId": "test_1383337059137", "conversionTimestamp": "1378710000000", "segmentationType" : "FLOODLIGHT", "segmentationName" : "Test", "type": "ACTION", "quantityMillis": "1000", "state": "REMOVED" } ] }
جافا
/** * Instantiate the Doubleclicksearch service, create a conversion that updates an existing conversion, * and upload the conversions. */ public static void main(String[] args) throws Exception { Doubleclicksearch service = getService(); // See Set Up Your Application. // Set up a List to keep track of each conversion you create. List<Conversion> conversions = new Vector<Conversion>(); // Create a conversion and add it to the conversion list. // Just to get a little fancy, the updateConversionFromVisit() method can be used for all // visit conversions, including conversions that don't specify quantity, revenue, or currency. // If quantityMillis wasn't specified in the original conversion, specify -1L for the // quantityMillis parameter. Likewise, if revenueMicros wasn't specified originally, // specify -1L for the revenueMicros parameter and an empty string for currency. conversionList = updateConversionFromVisit( conversionList, "COiYmPDTv7kCFcP0KgodOzQAAA", // clickId. Replace with data from your site "test_20130906_10", // conversionId 1378710000000L, // timeStamp "TRANSACTION", // type "", // state -1L, // quantityMillis 90000000L, // revenueMicros. Equivalent to $90 of revenue "USD"); // currencyCode // Here's a conversion that needs to be removed. Just set the state parameter to "REMOVED". conversionList = updateConversionFromVisit( conversionList, "COiYmPDTv7kCFcP0KgodOzQAAA", // clickId. Replace with data from your site "test_1383337059137", // conversionId 1378710000000L, // timeStamp "ACTION", // type "REMOVED", // state 1000L, // quantityMillis -1L, // revenueMicros ""); // currencyCode // Upload the List and handle the response. uploadConversions(conversions, service); // See an example in Add New Conversions. } /** * Create a conversion and add it to a List<Conversion>. */ private static List<Conversion> updateConversionFromVisit(List<Conversion> conversions, String clickId, String conversionId, Long timeStamp, String type, String state, Long quantity, Long revenue, String currency) { // Identifies the existing conversion. This sample hard-codes the segmentation name. Conversion conversion = new Conversion() .setClickId(clickId) .setConversionId(conversionId) .setConversionTimestamp(BigInteger.valueOf(timeStamp)) .setSegmentationType("FLOODLIGHT") .setSegmentationName("Test") .setType(type); // Only add these fields if the value is not empty greater than -1. if(!state.isEmpty()) conversion.setState(state); if (quantity > -1L) { conversion.setQuantityMillis(quantity); } if (revenue > -1L) { conversion.setRevenueMicros(revenue); if (!currency.isEmpty()) { conversion.setCurrencyCode(currency); } else { System.err.println(String.format( "Can't add conversion %s. It specifies revenue but no currency.", conversion.getConversionId())); return conversions; } } conversions.add(conversion); return conversions; }
Python
def update_conversion(service): """Change the revenue for one existing conversion and remove another. Args: service: An authorized Doubleclicksearch service. See Set Up Your Application. """ request = service.conversion().update( body= { 'conversion' : [{ 'clickId' : 'COiYmPDTv7kCFcP0KgodOzQAAA', // Replace with data from your site 'conversionId' : 'test_20130906_13', 'conversionTimestamp' : '1378710000000', 'segmentationType' : 'FLOODLIGHT', 'segmentationName' : 'Test', 'type': 'TRANSACTION', 'revenueMicros': '90000000', // 90 million revenueMicros is equivalent to $90 of revenue 'currencyCode': 'USD' }, { 'clickId': 'COiYmPDTv7kCFcP0KgodOzQAAA', // Replace with data from your site 'conversionId': 'test_1383337059137_01', 'conversionTimestamp': '1378710000000', 'segmentationType' : 'FLOODLIGHT', 'segmentationName' : 'Test', 'type': 'ACTION', 'quantityMillis': '1000', 'state': 'REMOVED' }] } ) pprint.pprint(request.execute())
تحديد الإحالة الناجحة حسب معرّف الكلمة الرئيسية
إذا لم يكن لديك إذن وصول إلى معرّف نقرة، أو إذا كانت الإحالة الناجحة منسوبة في الأصل إلى كلمة رئيسية أو كلمة رئيسية/إعلان، يمكنك إرسال طلب Conversion.update() يحدّد الحقول التالية:
-
customerIdوcampaignIdوadGroupIdوcriterionId(أرقام تعريف التجربة الجديدة من "إعلانات شبكة البحث 360" التي تحدّد الكلمة الرئيسية) conversionIdconversionTimestamptype-
state(مطلوب فقط إذا أردت تغيير الحالة إلى "تمت الإزالة" أو "نشط") -
quantityMillis(فقط في حال تحديدها في الإحالة الناجحة الأصلية) -
revenueMicros(فقط في حال تحديدها في الإحالة الناجحة الأصلية) -
currencyCode(فقط في حال تحديدها في الإحالة الناجحة الأصلية)
تكون معرّفات الكلمات الرئيسية فريدة فقط ضمن مجموعة إعلانية، لذا عليك تحديد المعرّفات الأربعة جميعها.
إذا حدّدت إحالة ناجحة السمة criterionId بدون customerId أو campaignId أو adGroupId، يتعذّر إجراء التعديل ويظهر رمز الخطأ 0x0000012E. لست بحاجة إلى تحديد معرّفات أخرى، مثل معرّف الإعلان للإحالة الناجحة.
مثال
في ما يلي مثال على إحالة ناجحة حالية:
{ "kind": "doubleclicksearch#conversionList", "conversion" : [{ "customerId": "123-456-7890", "campaignId": "14660344555", "adGroupId": "105138634255", "criterionId": "948710340465", "conversionId": "test_1383157519886", "conversionTimestamp": "1378710000000", "type": "ACTION", "quantityMillis": "1000", "segmentationType": "FLOODLIGHT", "segmentationName": "Test" }] }
يعدّل الطلب التالي كمية الإحالة الناجحة:
JSON
يُرجى العِلم أنّ طلب Conversion.update() يستخدم طريقة HTTP PUT.
PUT https://www.googleapis.com/doubleclicksearch/v2/conversion Authorization: Bearer your OAuth 2.0 access token Content-type: application/json { "kind": "doubleclicksearch#conversionList", "conversion": [ { "customerId": "123-456-7890", // Replace with your ID "campaignId": "14660344555", // Replace with your ID "adGroupId": "105138634255", // Replace with your ID "criterionId": "948710340465", // Replace with your ID "conversionId": "test_1383157519886", "conversionTimestamp": "1378710000000", "type": "ACTION", "quantityMillis": "3000" } ] }
جافا
// Send conversion data to updateConversion, which creates a conversion and adds it // to the conversion list. conversionList = updateConversionFromKeyword(conversionList, "123-456-7890", // customerId. Replace with your ID 14660344555L, // campaignId. Replace with your ID 105138634255L, // adGroupId. Replace with your ID 948710340465L, // criterionId. Replace with your ID "test_1383157519886", // conversionId 1378710000000L, // timeStamp "ACTION", // type "", // state 3000L, // quantityMillis -1L, // revenueMicros ""); // currencyCode private static List<Conversion> updateConversionFromKeyword(List<Conversion> conversions, String customerId, Long campaignId, Long adGroupId, Long criterionId, String conversionId, Long timeStamp, String type, String state, Long quantity, Long revenue, String currency ) { Conversion conversion = new Conversion() .setCustomerId(customerId) .setCampaignId(campaignId) .setAdGroupId(adGroupId) .setCriterionId(criterionId) .setConversionId(conversionId) .setConversionTimestamp(BigInteger.valueOf(timeStamp)) .setType(type); // Only add these fields if the value is not empty greater than -1. if(!state.isEmpty()) conversion.setState(state); if (quantity > -1L) { conversion.setQuantityMillis(quantity); } if (revenue > -1L) { conversion.setRevenueMicros(revenue); if (!currency.isEmpty()) { conversion.setCurrencyCode(currency); } else { System.err.println(String.format( "Can't add conversion %s. It specifies revenue but no currency.", conversion.getConversionId())); return conversions; } } conversions.add(conversion); return conversions; }
Python
def update_conversion(service): """Change the quantity of a conversion. Use the keyword's IDs (customerId, campaignId, adGroupId, and criterionId) to identify the conversion. Args: service: An authorized Doubleclicksearch service. See Set Up Your Application. """ request = service.conversion().update( body= { 'conversion': [{ 'customerId': '123-456-7890', // Replace with your ID 'campaignId': '14660344555', // Replace with your ID 'adGroupId': '105138634255', // Replace with your ID 'criterionId': '948710340465', // Replace with your ID 'conversionId': 'test_1383157519886', 'conversionTimestamp': '1378710000000', 'type': 'ACTION', 'quantityMillis': '3000' }] } ) pprint.pprint(request.execute())
التعامل مع استجابات "إعلانات شبكة البحث 360"
تكون الاستجابة لطلب تعديل مماثلة للاستجابة لطلب إدراج: تشير "إعلانات شبكة البحث 360" إلى النجاح فقط في حال تم تعديل جميع الإحالات الناجحة في الطلب بنجاح.
إذا نجح الطلب، سيتضمّن الردّ التمثيل الداخلي الكامل لكل إحالة ناجحة تم تعديلها في "إعلانات شبكة البحث 360"، مثل رقم تعريف العميل ورقم تعريف الحملة ورقم تعريف المجموعة الإعلانية ورقم تعريف الكلمة الرئيسية (المعيار) في التجربة الجديدة من "إعلانات شبكة البحث 360".
إذا تعذّر التحقّق من صحة تعديل واحد أو أكثر أو تعذّر تحميله، يتضمّن الردّ رسائل خطأ لكل تعديل تعذّر إجراؤه. لا يحتوي الردّ على رسائل حول الإحالات الناجحة التي تم تعديلها بنجاح. لمزيد من المعلومات عن رسائل الخطأ هذه، اطّلِع على التعامل مع ردود "إعلانات شبكة البحث 360" لطلبات الإدراج.