روش Conversion.update() را فراخوانی کنید تا انواع تغییرات زیر را در یک یا چند تبدیل موجود اعمال کنید:
- درآمد، کد ارز، یا تعداد را تغییر دهید.
- شناسه سفارش ارائهشده توسط آگهیدهنده و هرگونه متغیرهای سفارشی Floodlight را اصلاح کنید.
- با تغییر دادن
conversion.stateازACTIVEبهREMOVED، تبدیل را بردارید.
Search Ads 360 از تغییر موارد زیر پشتیبانی نمیکند:
- تاریخ تبدیل.
- نوع تبدیل.
- کلیدواژه یا بازدیدی که به تبدیل نسبت داده میشود.
- فعالیت Floodlight یا نام فعالیت.
بااینحال، همیشه میتوانید تبدیل موجودی را بهعنوان «برداشتهشده» علامتگذاری کنید و تبدیل جدیدی را با تاریخ، نوع، شناسههای اسنادی، یا فعالیت Floodlight بهروزشده بارگذاری کنید (حتماً conversionId جدیدی را نیز مشخص کنید).
میتوانید هم تبدیلهایی را که ازطریق Search Ads 360 API بارگذاری شدهاند (تبدیلهای آفلاین) و هم تبدیلهایی را که Search Ads 360 ازطریق برچسبهای Floodlight ضبط کرده است (تبدیلهای آنلاین) ویرایش کنید، مشروط به محدودیتهای زمانی زیر:
-
اگر تبدیل را با
clickIdشناسایی کنید، شناسه کلیک باید در ۶۰ روز گذشته تولید شده باشد (درغیراینصورت کد خطا0x0000012Fاست). -
تبدیلهای ثبتشده ازطریق برچسبهای Floodlight فقط درطول ۲۸ روز از
conversionTimestampقابلویرایش هستند (درغیراینصورت کد خطای0x00000125نشان داده میشود).
همانند Conversion.insert()، اگر درخواست بهروزرسانی شما چندین تبدیل را مشخص کند، Search Ads 360 تلاش میکند هر تبدیل را براساس بهترین تلاش بهروزرسانی کند، بهجای اینکه کل دسته را بهعنوان یک تراکنش همهیاهیچ بهروزرسانی کند. اگر برخیاز بهروزرسانیها در یک
دسته ناموفق باشد، ممکن است بقیه همچنان موفقیتآمیز باشد. توصیه میکنیم برای هر تبدیل بهروزشده، پاسخ را بخوانید تا مطمئن شوید بهروزرسانی موفقیتآمیز بوده است.
منسوخ شدن dsConversionId
فیلد dsConversionId منسوخ شده است و دیگر نمیتوان از آن برای شناسایی
تبدیلها استفاده کرد. برای ویرایش تبدیلها در Search Ads 360 Conversion API، باید از conversionId (شناسه تبدیل آگهیدهنده) استفاده کنید. Conversion.update()
تبدیل با کد خطای 0x0000013C (Conversion editing using
integer DS conversion ID is deprecated) را رد میکند اگر تبدیل:
- فیلد
dsConversionIdرا مشخص میکند، یا - شناسه تبدیل Search Ads 360 (شناسه عددی ۱۷ رقمی که
Search Ads 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موردنیاز برای ویرایش مطابقت دارد. -
میانای کاربر Search Ads 360: میتوانید «شناسه تبدیل آگهیدهنده» را در
صفحه گزارشدهی تبدیل در میانای کاربر Search Ads 360 پیدا کنید.
ارسال درخواست بهروزرسانی
بیشتر فیلدهایی که در Conversion.update() مشخص میکنید برای شناسایی تبدیلهایی که میخواهید بهروز کنید استفاده میشوند. میتوانید از هریک از روشهای زیر
برای شناسایی تبدیل موجود استفاده کنید:
clickIdتبدیل را مشخص کنید- همه تبدیلهای ویرایششده باید ظرف ۶۰ روز از زمان تولید شناسه کلیک باشند.
- کلیدواژه تبدیل را مشخص کنید (
customerId،campaignId،adGroupId، وcriterionId)
هر دو روش مستلزم این است که conversionId، conversionTimestamp، و type تراکنش تبدیل را مشخص کنید. conversionTimestamp باید مُهر زمان
تبدیل موجود، در میلیثانیه Epoch UTC باشد. اگر مُهر زمان با تبدیل موجود مطابقت نداشته باشد (برای مثال، چون از منطقه زمانی محلی تبدیل شده است)، Search Ads 360 نمیتواند تبدیل را پیدا کند و کد خطای 0x0000011B را برمیگرداند.
برای تبدیلهایی که Search Ads 360 ازطریق برچسبهای Floodlight ثبت کرده است، باید فعالیت Floodlight تبدیل را نیز مشخص کنید (segmentationType و segmentationName یا segmentationId). درغیراینصورت، درخواست با کد خطای 0x0000010C ناموفق خواهد بود. توصیه میکنیم که فعالیت Floodlight را در هر درخواست بهروزرسانی مشخص کنید.
علاوهبراین، اگر تبدیل اصلی revenueMicros و currencyCode یا quantityMillis را مشخص کرده باشد، درخواست بهروزرسانی باید این دادهها را مشخص کند، حتی اگر آنها را تغییر ندهید.
شناسایی تبدیل با شناسه کلیک
اگر تبدیلی در ابتدا شناسه کلیک را مشخص کرده باشد، میتوانید Conversion.update()
درخواستی ارسال کنید که فیلدهای زیر را مشخص کند:
clickIdconversionIdconversionTimestamptypesegmentationTypeو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(شناسههای Search Ads 360 جدید که کلیدواژه را شناسایی میکنند)conversionIdconversionTimestamptypestate(فقط اگر میخواهید وضعیت را به «برداشتهشده» یا «فعال» تغییر دهید الزامی است)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())
مدیریت پاسخهای Search Ads 360
پاسخ درخواست بهروزرسانی همانند پاسخ درخواست درج است: Search Ads 360 تنها درصورتی موفقیت را نشان میدهد که همه تبدیلهای موجود در درخواست باموفقیت بهروز شده باشند.
اگر درخواست موفقیتآمیز باشد، پاسخ شامل نمایش داخلی کامل Search Ads 360 برای هر تبدیل بهروزشده است، مانند شناسه مشتری جدید Search Ads 360، شناسه کمپین، شناسه گروه آگهی، و شناسه کلیدواژه (معیار).
اگر یک یا چند بهروزرسانی اعتبارسنجی یا بارگذاری نشود، پاسخ شامل پیامهای ناموفق برای هر بهروزرسانی ناموفق است. پاسخ حاوی پیامهایی درباره تبدیلهایی که باموفقیت بهروز شدهاند نیست. برای اطلاعات بیشتر درباره این پیامهای خطا، به رسیدگی به پاسخهای Search Ads 360 برای درخواستهای درج مراجعه کنید.