מפעילים את השיטה Conversion.update()
כדי לבצע את השינויים הבאים בהמרה קיימת אחת או יותר:
- משנים את ההכנסה, קוד המטבע או הכמות.
- משנים את מזהה ההזמנה שסופק על ידי המפרסם ואת כל המשתנים המותאמים אישית של Floodlight.
- כדי להסיר את ההמרה, משנים את הערך
conversion.state
מ-ACTIVE
ל-REMOVED
.
ב-Search Ads 360 אין תמיכה בביצוע השינויים הבאים:
- תאריך ההמרה.
- סוג ההמרה
- מילת המפתח או הביקור שמשויכים להמרה.
- הפעילות ב-Floodlight או השם שלה
עם זאת, תמיד אפשר לסמן המרה קיימת כ'הוסרה' ולהעלות המרה חדשה
עם התאריך המעודכן, הסוג המעודכן, מזהי השיוך (Attribution) או הפעילות ב-Floodlight (חשוב לציין גם
conversionId
חדש).
כמו במקרה של Conversion.insert()
, אם בבקשת העדכון צוינו מספר המרות, מערכת Search Ads 360 מנסה לעדכן כל המרה ללא שגיאות, במקום לעדכן את כל ההמרות כעסקה מסוג 'הכול או כלום'. אם חלק מהעדכונים בכמות גדולה ייכשלו, יכול להיות שעדכונים אחרים עדיין יצליחו. מומלץ לקרוא
את התגובה לגבי כל המרה מעודכנת כדי לוודא שהעדכון בוצע בהצלחה.
שליחת בקשה לעדכון
רוב השדות שמציינים ב-Conversion.update()
משמשים
לזיהוי ההמרות שרוצים לעדכן. אפשר להשתמש באחת מהשיטות הבאות כדי לזהות המרה קיימת:
- מציינים את
clickId
- של ההמרה
- כל ההמרות שנערכו צריכות להתרחש תוך 60 יום ממועד היצירה של מספר הקליק.
- לציין את
criterionId
של ההמרה (מזהה מילת מפתח)
בשתי השיטות האלה צריך לציין את conversionId
, conversionTimestamp
ואת העסקה type
של ההמרה.
בנוסף, אם ההמרה המקורית מציינת את הנתונים revenueMicros
ו-currencyCode
או quantityMillis
, בקשת העדכון צריכה לציין את הנתונים האלה גם אם
לא משנים אותם.
זיהוי המרה לפי מספר קליק
אם במקור ההמרה צוינה מזהה קליק, אפשר לשלוח בקשת Conversion.update()
שמציינת את השדות הבאים:
clickId
conversionId
conversionTimestamp
type
state
(נדרשת רק אם רוצים לשנות את המדינה ל-הוסרה או ל-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()
משתמשת ב-method 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
(נדרשת רק אם רוצים לשנות את המדינה ל-הוסרה או ל-ACTIVE)quantityMillis
(רק אם צוין בהמרה המקורית)revenueMicros
(רק אם צוין בהמרה המקורית)currencyCode
(רק אם צוין בהמרה המקורית)
אפשר לציין מזהים אחרים, כמו מזהה המודעה, מזהה הקמפיין של ההמרה וכן הלאה, אבל אין צורך בכך. כדי לזהות המרה קיימת, מערכת Search Ads 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()
משתמשת ב-method 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())
טיפול בתשובות של Search Ads 360
התגובה לבקשת עדכון זהה לתשובה לבקשת הוספה: מערכת Search Ads 360 מציינת הצלחה רק אם כל ההמרות בבקשה עודכנו בהצלחה.
אם הבקשה תתבצע בהצלחה, התשובה תכלול את הייצוג הפנימי המלא של Search Ads 360 לכל המרה מעודכנת, כמו מזהה הקמפיין, מזהה קבוצת המודעות והמזהה של מילת המפתח (קריטריון).
אם עדכון אחד או יותר נכשל באימות או בהעלאה, התשובה כוללת הודעות על כשל בכל עדכון שנכשל. התשובה לא מכילה הודעות על המרות שעודכנו בהצלחה. מידע נוסף על ההודעות האלה נכשל במאמר טיפול בתשובות של Search Ads 360 לבקשות הוספה.