ערוך המרות

המדריך הזה כולל הוראות מפורטות לעריכת המרות באמצעות השירות 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 כדי לבדוק במהירות אם המרה כלשהי בקבוצה שצוינה נכשלה. בשאלות הנפוצות מוסבר איך לטפל בכל קוד שגיאה, ובאילו המרות שנכשלו כדאי לנסות שוב (INTERNAL ו-NOT_FOUND).