ערוך המרות

במדריך הזה מפורטות הוראות לעריכת המרות באמצעות השירות Conversions של Campaign Manager 360 API. לפני שממשיכים, מומלץ לעיין בסקירה הכללית כדי לקבל מבוא להמרות אופליין ולהכיר את המושגים שמוסברים במדריך הזה.

לפני שמתחילים

תהליך העבודה הזה מאפשר לכם לשנות את quantity וvalue של המרות קיימות אונליין ואופליין. כדי לעשות זאת, תצטרכו לספק ערכים שמזהים באופן ייחודי את ההמרות שרוצים לערוך. בהתאם לסוג ההמרות שאתם עורכים, תקבלו את הערכים האלה בדרכים שונות:

אחרי שתערכו בהצלחה המרה מכל סוג שהוא, התג ConversionsBatchUpdateResponse יכיל את הערכים הדרושים לביצוע עריכות נוספות.

הגדרת משאבי המרות

השלב הראשון בתהליך העבודה של עריכה הוא יצירה של אובייקט משאב אחד או יותר Conversion.

השדות הבאים משמשים לזיהוי המרה שרוצים לערוך. חובה למלא את השדות האלה, והם צריכים להיות זהים בדיוק להמרה קיימת.

שדה תיאור

‫encryptedUserId או gclid או dclid או matchid או mobileDeviceId

 מזהה משתמש מוצפן, מספר קליק ב-Google, מספר קליק ברשת המדיה, מזהה התאמה או מזהה מכשיר נייד שבאמצעותו נוצרה ההמרה.
floodlightActivityId הפעילות ב-Floodlight שאליה משויכת ההמרה.
floodlightConfigurationId ההגדרה של Floodlight שבה נעשה שימוש בפעילות שצוינה.
ordinal מזהה ביטול הכפילויות שמשויך להמרה.
timestampMicros חותמת הזמן של ההמרה, במיקרו-שניות מאז ראשית זמן יוניקס (Unix epoch).

בהמשך מפורטים השדות שאפשר לערוך.

השדות האלה הם שדות חובה, והערכים שתספקו יחליפו את כל הערכים הקיימים בהמרה שאתם עורכים.

שדה תיאור
quantity מספר הפריטים שמשויכים להמרה.
value סכום ההכנסה שנוצר מההמרה.

השדות האלה הם אופציונליים. אם לא תגדירו ערך, הוא לא ישתנה.

שדה תיאור
customVariables המשתנים המותאמים אישית ב-Floodlight של ההמרה. הערך יעודכן או יתווסף אם המשתנה מוגדר. אם לא מגדירים את הערך של המשתנה, הוא לא משתנה.

כל השדות האחרים שמוזכרים במסמכי העיון לא נתמכים ולא ניתן לשנות אותם. אם תכללו בשדה הבקשה לעריכה שדות שלא נתמכים, תתקבל שגיאה. אם ההמרה שעורכים מכילה ערכים קיימים בשדות לא נתמכים, הערכים האלה יישמרו באופן אוטומטי.

בדוגמה הבאה מוצג אובייקט פשוט של משאב המרה שנוצר כדי לערוך אותו:

C#‎

// Find the Floodlight configuration ID based on the provided activity ID.
FloodlightActivity floodlightActivity =
    service.FloodlightActivities.Get(profileId, floodlightActivityId).Execute();
long floodlightConfigurationId = (long) floodlightActivity.FloodlightConfigurationId;

// Construct the conversion object with values that identify the conversion to update.
Conversion conversion = new Conversion();
conversion.EncryptedUserId = conversionUserId;
conversion.FloodlightActivityId = floodlightActivityId;
conversion.FloodlightConfigurationId = floodlightConfigurationId;
conversion.Ordinal = conversionOrdinal;
conversion.TimestampMicros = conversionTimestamp;

// Set the fields to be updated. These fields are required; to preserve a value from the
// existing conversion, it must be copied over manually.
conversion.Quantity = newQuantity;
conversion.Value = newValue;

Java

// Create a conversion object populated with values that identify the conversion to update.
Conversion conversion = new Conversion();
conversion.setEncryptedUserId(encryptedUserId);
conversion.setFloodlightActivityId(floodlightActivityId);
conversion.setFloodlightConfigurationId(floodlightConfigurationId);
conversion.setOrdinal(ordinal);
conversion.setTimestampMicros(timestampMicros);

// Set the fields to be updated. These fields are required; to preserve a value from the
// existing conversion, it must be copied over manually.
conversion.setQuantity(newQuantity);
conversion.setValue(newValue);

PHP

// Find Floodlight configuration ID based on provided activity ID.
$activity = $this->service->floodlightActivities->get(
    $values['user_profile_id'],
    $values['floodlight_activity_id']
);
$floodlightConfigId = $activity->getFloodlightConfigurationId();

// Create a conversion object with values that identify the conversion to
// update.
$conversion = new Google_Service_Dfareporting_Conversion();
$conversion->setEncryptedUserId($values['encrypted_user_id']);
$conversion->setFloodlightActivityId($values['floodlight_activity_id']);
$conversion->setFloodlightConfigurationId($floodlightConfigId);
$conversion->setOrdinal($values['ordinal']);
$conversion->setTimestampMicros($values['timestamp']);

// Set the fields to be updated. These fields are required; to preserve a
// value from the existing conversion, it must be copied over manually.
$conversion->setQuantity($values['new_quantity']);
$conversion->setValue($values['new_value']);

Python

# Construct the conversion object with values that identify the conversion
# to update.
conversion = {
    'encryptedUserId': encrypted_user_id,
    'floodlightActivityId': floodlight_activity_id,
    'floodlightConfigurationId': floodlight_config_id,
    'ordinal': ordinal,
    'timestampMicros': timestamp
}

# Set the fields to be updated. These fields are required; to preserve a
# value from the existing conversion, it must be copied over manually.
conversion['quantity'] = new_quantity
conversion['value'] = new_value

Ruby

# Look up the Floodlight configuration ID based on activity ID.
floodlight_activity = service.get_floodlight_activity(profile_id,
  existing_conversion[:floodlight_activity_id])
floodlight_config_id = floodlight_activity.floodlight_configuration_id

# Construct the conversion with values that identify the conversion to
# update.
conversion = DfareportingUtils::API_NAMESPACE::Conversion.new(
  encrypted_user_id: existing_conversion[:encrypted_user_id],
  floodlight_activity_id: existing_conversion[:floodlight_activity_id],
  floodlight_configuration_id: floodlight_config_id,
  ordinal: existing_conversion[:ordinal],
  timestamp_micros: existing_conversion[:timestamp]
)

# Set the fields to be updated. These fields are required; to preserve a
# value from the existing conversion, it must be copied over manually.
conversion.quantity = new_quantity
conversion.value = new_value

ציון פרטי ההצפנה

אם ההמרות שרוצים לערוך משויכות למזהי משתמשים מוצפנים, צריך לספק פרטים על אופן ההצפנה שלהם כחלק מבקשת העריכה. פרטים נוספים זמינים במדריך בנושא העלאת המרות.

במקרה הצורך, השלב השני בתהליך העריכה הוא יצירת אובייקט EncryptionInfo שמציין את הערכים האלה:

C#‎

// Create the encryption info.
EncryptionInfo encryptionInfo = new EncryptionInfo();
encryptionInfo.EncryptionEntityId = encryptionEntityId;
encryptionInfo.EncryptionEntityType = encryptionEntityType;
encryptionInfo.EncryptionSource = encryptionSource;

Java

// Create the encryption info.
EncryptionInfo encryptionInfo = new EncryptionInfo();
encryptionInfo.setEncryptionEntityId(encryptionEntityId);
encryptionInfo.setEncryptionEntityType(encryptionEntityType);
encryptionInfo.setEncryptionSource(encryptionSource);

PHP

$encryptionInfo = new Google_Service_Dfareporting_EncryptionInfo();
$encryptionInfo->setEncryptionEntityId($values['encryption_entity_id']);
$encryptionInfo->setEncryptionEntityType($values['encryption_entity_type']);
$encryptionInfo->setEncryptionSource($values['encryption_source']);

Python

# Construct the encryption info.
encryption_info = {
    'encryptionEntityId': encryption_entity_id,
    'encryptionEntityType': encryption_entity_type,
    'encryptionSource': encryption_source
}

Ruby

# Construct the encryption info.
encryption_info = DfareportingUtils::API_NAMESPACE::EncryptionInfo.new(
  encryption_entity_id: encryption[:entity_id],
  encryption_entity_type: encryption[:entity_type],
  encryption_source: encryption[:source]
)

יצירת בקשה לעדכון

השלב האחרון בתהליך הזה הוא לערוך את ההמרות באמצעות קריאה ל-batchupdate. השיטה הזו מקבלת אובייקט ConversionsBatchUpdateRequest, שמשלב את קבוצת ההמרות שרוצים לערוך עם פרטי ההצפנה המשויכים (במקרה הצורך):

C#‎

// Insert the conversion.
ConversionsBatchUpdateRequest request = new ConversionsBatchUpdateRequest();
request.Conversions = new List<Conversion>() { conversion };
request.EncryptionInfo = encryptionInfo;

ConversionsBatchUpdateResponse response =
    service.Conversions.Batchupdate(request, profileId).Execute();

Java

ConversionsBatchUpdateRequest request = new ConversionsBatchUpdateRequest();
request.setConversions(ImmutableList.of(conversion));
request.setEncryptionInfo(encryptionInfo);

ConversionsBatchUpdateResponse response = reporting.conversions()
    .batchupdate(profileId, request).execute();

PHP

$batch = new Google_Service_Dfareporting_ConversionsBatchUpdateRequest();
$batch->setConversions([$conversion]);
$batch->setEncryptionInfo($encryptionInfo);

$result = $this->service->conversions->batchupdate(
    $values['user_profile_id'],
    $batch
);

Python

# Update the conversion.
request_body = {
    'conversions': [conversion],
    'encryptionInfo': encryption_info
}
request = service.conversions().batchupdate(
    profileId=profile_id, body=request_body)
response = request.execute()

Ruby

# Construct the batch update request.
batch_update_request =
  DfareportingUtils::API_NAMESPACE::ConversionsBatchUpdateRequest.new(
    conversions: [conversion],
    encryption_info: encryption_info
  )

# Update the conversion.
result = service.batchupdate_conversion(profile_id, batch_update_request)

חשוב לדעת שב-Campaign Manager 360 המערכת מנסה לערוך כל המרה בבקשה שלכם על בסיס המאמץ המרבי, במקום לעדכן את כל ההמרות כעסקה של הכול או כלום. אם העדכון של חלק מההמרות בחבילה נכשל, יכול להיות שהעדכון של המרות אחרות יצליח. לכן, מומלץ לבדוק את הערך ConversionsBatchUpdateResponse שמוחזר כדי לקבוע את הסטטוס של כל המרה:

C#‎

// Handle the batchinsert response.
if (!response.HasFailures.Value) {
  Console.WriteLine("Successfully updated conversion for encrypted user ID {0}.",
      conversionUserId);
} else {
  Console.WriteLine("Error(s) updating conversion for encrypted user ID {0}:",
      conversionUserId);

  ConversionStatus status = response.Status[0];
  foreach(ConversionError error in status.Errors) {
    Console.WriteLine("\t[{0}]: {1}", error.Code, error.Message);
  }
}

Java

if (!response.getHasFailures()) {
  System.out.printf("Successfully updated conversion for encrypted user ID %s.%n",
      encryptedUserId);
} else {
  System.out.printf("Error(s) updating conversion for encrypted user ID %s:%n",
      encryptedUserId);

  // Retrieve the conversion status and report any errors found. If multiple conversions
  // were included in the original request, the response would contain a status for each.
  ConversionStatus status = response.getStatus().get(0);
  for (ConversionError error : status.getErrors()) {
    System.out.printf("\t[%s]: %s.%n", error.getCode(), error.getMessage());
  }
}

PHP

if (!$result->getHasFailures()) {
    printf(
        'Successfully updated conversion for encrypted user ID %s.',
        $values['encrypted_user_id']
    );
} else {
    printf(
        'Error(s) updating conversion for encrypted user ID %s:<br><br>',
        $values['encrypted_user_id']
    );

    $status = $result->getStatus()[0];
    foreach ($status->getErrors() as $error) {
        printf('[%s] %s<br>', $error->getCode(), $error->getMessage());
    }
}

Python

if not response['hasFailures']:
  print('Successfully updated conversion for encrypted user ID %s.' %
        encrypted_user_id)
else:
  print('Error(s) updating conversion for encrypted user ID %s.' %
        encrypted_user_id)

  status = response['status'][0]
  for error in status['errors']:
    print '\t[%s]: %s' % (error['code'], error['message'])

Ruby

if result.has_failures
  puts format('Error(s) updating conversion for encrypted user ID %s.',
    existing_conversion[:encrypted_user_id])

  status = result.status[0]
  status.errors.each do |error|
    puts format("\t[%s]: %s", error.code, error.message)
  end
else
  puts format('Successfully updated conversion for encrypted user ID %s.',
    existing_conversion[:encrypted_user_id])
end

השדה status בתגובה, כפי שמוצג למעלה, יכיל אובייקט ConversionStatus לכל המרה שכלולה בבקשה המקורית. אם אתם רוצים לדעת רק על המרות שלא עודכנו, אפשר להשתמש בשדה hasFailures כדי לגלות במהירות אם הייתה המרה אחת לפחות באצווה שסופקה שלא עודכנה.