ערוך המרות

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

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

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

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

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

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

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

שדה תיאור

encryptedUserId או gclid או dclicd או matchid או mobileDeviceId

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

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

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

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

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

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 כדי לקבוע במהירות אם המרה כלשהי בקבוצה הנתונה נכשלה.