דף זה תורגם על ידי Cloud Translation API.

ערוך המרות

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

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

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

אפשר לקבל את הערכים הנדרשים לזיהוי המרות אונליין מהעברת נתונים.
הערכים הנדרשים לזיהוי המרות אופליין מוחזרים ב-ConversionsBatchInsertResponse של בקשות batchinsert שהצליחו.

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

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

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

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

שדה	תיאור
`encryptedUserId` או `gclid` או `dclid` או `matchid` או `mobileDeviceId`	מזהה המשתמש המוצפן, מספר הקליק ב-Google, מספר הקליק ברשת המדיה, מזהה ההתאמה או מזהה המכשיר הנייד שהניבו את ההמרה. לא ניתן להשתמש בשדה `encryptedUserIdCandidates` לעריכה.
`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 כדי לקבוע במהירות אם אחת מההמרות בקבוצה שצוינה נכשלה.