استدعِ الطريقة Conversion.update()
لإجراء الأنواع التالية من التغييرات على إحالة ناجحة حالية واحدة أو أكثر:
- تعديل الأرباح أو رمز العملة أو الكمية
- عدِّل مُعرّف الطلب المقدّم من المعلِن وأي متغيّرات Floodlight مخصّصة.
- أزِل الإحالة الناجحة عن طريق تغيير
conversion.state
منACTIVE
إلىREMOVED
.
لا تتيح "إعلانات شبكة البحث 360" تغيير ما يلي:
- تاريخ الإحالة الناجحة.
- نوع التحويل.
- الكلمة الرئيسية أو الإعلان أو الزيارة المنسوبة إلى الإحالة الناجحة.
- نشاط Floodlight أو اسم النشاط
ومع ذلك، يمكنك دائمًا وضع علامة "تمت الإزالة" على إحالة ناجحة حالية وتحميل إحالة ناجحة جديدة
باستخدام التاريخ المعدَّل أو النوع أو أرقام تعريف الإحالة أو نشاط Floodlight (احرص على تحديد
conversionId
جديدة أيضًا).
كما هو الحال مع Conversion.insert()
، إذا كان طلب التحديث يحدّد إحالات ناجحة متعددة، تحاول "إعلانات شبكة البحث 360" تحديث كل إحالة ناجحة على أساس بذل أفضل جهد بدلاً من تحديث المجموعة بأكملها كمعاملة شاملة أو بدونها. وفي حال تعذّر إجراء بعض التعديلات
على دفعة واحدة، قد يستمر نجاح البعض الآخر. نقترح عليك قراءة الرد لكل إحالة ناجحة معدّلة للتأكد من نجاح التحديث.
إرسال طلب تحديث
ويتم استخدام معظم الحقول التي تحدّدها في Conversion.update()
لتحديد الإحالات الناجحة التي تريد تعديلها. يمكنك استخدام أحد الأساليب التالية
لتحديد إحالة ناجحة حالية:
- تحديد
clickId
للإحالة الناجحة - تحديد
criterionId
للإحالة الناجحة (رقم تعريف الكلمة الرئيسية)
تتطلب منك كلتا التقنيتين تحديد conversionId
وconversionTimestamp
والمعاملة type
للإحالة الناجحة.
بالإضافة إلى ذلك، إذا حدّدت الإحالة الناجحة الأصلية revenueMicros
وcurrencyCode
أو quantityMillis
، يجب أن يحدّد طلب التعديل هذه البيانات حتى إذا
لم تغيّرها.
تحديد الإحالة الناجحة حسب معرّف النقرة
إذا حدّدت إحالة ناجحة في الأصل معرّف نقرة، يمكنك إرسال طلب Conversion.update()
يحدّد الحقول التالية:
clickId
conversionId
conversionTimestamp
type
state
(مطلوبة فقط إذا كنت تريد تغيير الولاية إلى REMOVED أو ACTIVE)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", "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", "type": "ACTION", "quantityMillis": "1000", "state": "REMOVED" } ] }
لغة Java
/** * 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. Conversion conversion = new Conversion() .setClickId(clickId) .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 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()
يحدّد الحقول التالية:
criterionId
(رقم تعريف الكلمة الرئيسية)conversionId
conversionTimestamp
type
state
(مطلوبة فقط إذا كنت تريد تغيير الولاية إلى REMOVED أو ACTIVE)quantityMillis
(فقط إذا تم تحديدها في الإحالة الناجحة الأصلية)revenueMicros
(فقط إذا تم تحديدها في الإحالة الناجحة الأصلية)currencyCode
(فقط إذا تم تحديدها في الإحالة الناجحة الأصلية)
ويمكنك تحديد معرّفات أخرى اختياريًا، مثل الرقم التعريفي لإعلان الإحالة الناجحة ورقم تعريف الحملة، وما إلى ذلك، ولكنك لا تحتاج إلى ذلك. تحتاج "إعلانات شبكة البحث 360" فقط إلى أرقام التعريف في القائمة أعلاه لتحديد إحالة ناجحة حالية.
مثال
في ما يلي مثال للتحويل الحالي:
{ "kind": "doubleclicksearch#conversionList", "conversion" : [{ "agencyId": "12300000000000456", "advertiserId": "45600000000010291", "engineAccountId": "700000000042441", "campaignId": "71700000002044839", "adGroupId": "58700000032026064", "criterionId": "43700004289911004", "adId": "44700000155906860", "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": [ { "criterionId": "43700004289911004", // Replace with your ID "conversionId": "test_1383157519886", "conversionTimestamp": "1378710000000", "type": "ACTION", "quantityMillis": "3000" } ] }
لغة Java
// Send conversion data to updateConversion, which creates a conversion and adds it // to the conversion list. conversionList = updateConversionFromKeyword(conversionList, 43700004289911004L, // 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, Long criterionId, String conversionId, Long timeStamp, String type, String state, Long quantity, Long revenue, String currency ) { Conversion conversion = new Conversion() .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 timestamp of a conversion. Use only the keyword id (criterionId) to identify the conversion. Args: service: An authorized Doubleclicksearch service. See Set Up Your Application. """ request = service.conversion().update( body= { 'conversion': [{ 'criterionId': '43700004289911004', // Replace with your ID 'conversionId': 'test_1383157519886', 'conversionTimestamp': '1378760000000', 'type': 'ACTION', 'quantityMillis': '1000' }] } ) pprint.pprint(request.execute())
معالجة ردود "إعلانات شبكة البحث 360"
الاستجابة لطلب تعديل هي نفسها الاستجابة لطلب إدراج: تشير "إعلانات شبكة البحث 360" إلى النجاح فقط في حال تحديث جميع الإحالات الناجحة في الطلب بنجاح.
في حال نجاح الطلب، ستتضمّن الاستجابة التمثيل الداخلي الكامل في "إعلانات شبكة البحث 360" لكل إحالة ناجحة معدّلة، مثل رقم تعريف الحملة ورقم تعريف المجموعة الإعلانية ورقم تعريف الكلمة الرئيسية (المعيار).
إذا تعذّر على عملية تحديث واحدة أو أكثر التحقق من صحة التحميل أو التحميل، ستتضمّن الاستجابة رسائل تعذّر لكل عملية تعذّر. لا تحتوي الاستجابة على رسائل عن الإحالات الناجحة التي تم تعديلها بنجاح. لمزيد من المعلومات عن رسائل الإخفاق هذه، اطّلِع على التعامل مع "إعلانات شبكة البحث 360" لطلبات الإدراج.