העלאת המרות

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

הערה: למרות שה-API תומך בהמרות אופליין ב-Campaign Manager 360 וב-Display & Video 360, נתונים מעגלות קניות לא זמינים באף אחד מהמוצרים האלה. מידע נוסף על נתוני עגלות קניות

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

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

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

בנוסף, כל אובייקט חייב להכיל אחד מהשדות הבאים:

שדה	תיאור
encryptedUserId	מזהה משתמש מוצפן יחיד שמתקבל מפקודת המאקרו להתאמה%m או מהעברת נתונים.
encryptedUserIdCandidates[]	רשימה של מזהי משתמשים מוצפנים שהתקבלו מפקודת המאקרו להתאמה%m או מהעברת נתונים. המערכת תשתמש במזהה הראשון מבין המזהים האלה שמתועדת לגביו חשיפה ל-Floodlight לפני התאריך שצוין timestampMicros. אם אף אחד מהמזהים לא תואם לחשיפה קיימת, תוצג שגיאה.
dclid	מספר קליק ברשת המדיה שנוצר ב-Campaign Manager 360 או ב-Display & Video 360.
gclid	מספר קליק ב-Google‏ (GCLID) שנוצר ב-Google Ads או ב-Search Ads 360.
matchId	מזהה ייחודי שנוצר על ידי המפרסם ומועבר ל-Campaign Manager 360 דרך תג Floodlight.
mobileDeviceId	מזהה לא מוצפן לנייד בפורמט IDFA או AdID או מזהה פרסום (IFA) לטלוויזיות מחוברות ממכשיר CTV נתמך (Roku,‏ Fire TV,‏ Android TV,‏ Apple TV, ‏ Xbox,‏ Samsung,‏ Vizio). שימו לב: Google לא תומכת במזהי IFA ל-YouTube בטלוויזיות מחוברות (CTV).

לבסוף, לכל המרה יש שני מדדים:

שדה	תיאור
quantity	חובה. מספר הפריטים שמשויכים להמרה. הערך חייב להיות לפחות 1 כדי שההמרה תיכלל בחישוב של מדדים מסוימים (כמו 'המרות כוללות').
value	סכום הדולרים שמשויך להמרה. מפורש במטבע של המפרסם שאליו שייכת ההגדרה של Floodlight.

השדות האופציונליים מתועדים במסמכי העזר.

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

C#‎

// Generate a timestamp in milliseconds since Unix epoch.
TimeSpan timeSpan = DateTime.UtcNow - new DateTime(1970, 1, 1);
long currentTimeInMilliseconds = (long) timeSpan.TotalMilliseconds;

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

// Create the conversion.
Conversion conversion = new Conversion();
conversion.EncryptedUserId = conversionUserId;
conversion.FloodlightActivityId = floodlightActivityId;
conversion.FloodlightConfigurationId = floodlightConfigurationId;
conversion.Ordinal = currentTimeInMilliseconds.ToString();
conversion.TimestampMicros = currentTimeInMilliseconds * 1000;

Java

long currentTimeInMilliseconds = System.currentTimeMillis();

// Find Floodlight configuration ID based on the provided activity ID.
FloodlightActivity floodlightActivity = reporting.floodlightActivities()
    .get(profileId, floodlightActivityId).execute();
long floodlightConfigurationId = floodlightActivity.getFloodlightConfigurationId();

Conversion conversion = new Conversion();
conversion.setEncryptedUserId(encryptedUserId);
conversion.setFloodlightActivityId(floodlightActivityId);
conversion.setFloodlightConfigurationId(floodlightConfigurationId);
conversion.setOrdinal(String.valueOf(currentTimeInMilliseconds));
conversion.setTimestampMicros(currentTimeInMilliseconds * 1000);

PHP

$currentTimeInMicros = time() * 1000 * 1000;

// 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();

$conversion = new Google_Service_Dfareporting_Conversion();
$conversion->setEncryptedUserId($values['encrypted_user_id']);
$conversion->setFloodlightActivityId($values['floodlight_activity_id']);
$conversion->setFloodlightConfigurationId($floodlightConfigId);
$conversion->setOrdinal($currentTimeInMicros);
$conversion->setTimestampMicros($currentTimeInMicros);

Python

# Look up the Floodlight configuration ID based on activity ID.
floodlight_activity = (
    service.floodlightActivities()
    .get(profileId=str(profile_id), id=str(floodlight_activity_id))
    .execute()
)
floodlight_config_id = floodlight_activity['floodlightConfigurationId']

current_time_in_micros = int(time.time() * 1000000)

# Construct the conversion.
conversion = {
    'encryptedUserId': encrypted_user_id,
    'floodlightActivityId': floodlight_activity_id,
    'floodlightConfigurationId': floodlight_config_id,
    'ordinal': current_time_in_micros,
    'timestampMicros': current_time_in_micros
}

Ruby

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

current_time_in_micros = DateTime.now.strftime('%Q').to_i * 1000

# Construct the conversion.
conversion = DfareportingUtils::API_NAMESPACE::Conversion.new(
  encrypted_user_id: encrypted_user_id,
  floodlight_activity_id: floodlight_activity_id,
  floodlight_configuration_id: floodlight_config_id,
  ordinal: current_time_in_micros,
  timestamp_micros: current_time_in_micros
)

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

הערה: הקטע הזה רלוונטי רק כשמעלים המרות שמכילות encryptedUserId או encryptedUserIdCandidates[].

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

1. מקור ההצפנה, שמתאר מאיפה הגיעו קבוצה של מזהים מוצפנים. הערכים הקבילים הם AD_SERVING למזהים שמקורם בפקודת המאקרו %m match, או DATA_TRANSFER למזהים שמקורם בקבצים של העברת נתונים.

2. ישויות ההצפנה, שהן קבוצה ייחודית של ערכים שמשמשים להצפנה של מזהי משתמשים. הערכים האלה בדרך כלל קשורים לחשבון Campaign Manager 360 כשהמקור הוא העברת נתונים, או למפרסם ב-Campaign Manager 360 כשהמקור הוא מאקרו ‎ %m, אבל זה לא תמיד המצב. אם אתם לא בטוחים, אתם יכולים לפנות לנציג שלכם בחשבון Campaign Manager 360 או לתמיכה של Campaign Manager 360 כדי לקבל מידע נוסף.

במקרה הצורך, יצירת אובייקט 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]
)

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

יצירת בקשה להוספה

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

C#‎

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

ConversionsBatchInsertResponse response =
    service.Conversions.Batchinsert(request, profileId).Execute();

Java

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

ConversionsBatchInsertResponse response = reporting.conversions()
    .batchinsert(profileId, request).execute();

PHP

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

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

Python

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

Ruby

# Construct the batch insert request.
batch_insert_request =
  DfareportingUtils::API_NAMESPACE::ConversionsBatchInsertRequest.new(
    conversions: [conversion],
    encryption_info: encryption_info
  )

# Insert the conversion.
result = service.batchinsert_conversion(profile_id, batch_insert_request)

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

C#‎

// Handle the batchinsert response.
if (!response.HasFailures.Value) {
  Console.WriteLine("Successfully inserted conversion for encrypted user ID {0}.",
      conversionUserId);
} else {
  Console.WriteLine("Error(s) inserting 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 inserted conversion for encrypted user ID %s.%n",
      encryptedUserId);
} else {
  System.out.printf("Error(s) inserting 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 inserted conversion for encrypted user ID %s.',
        $values['encrypted_user_id']
    );
} else {
    printf(
        'Error(s) inserting 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 inserted conversion for encrypted user ID %s.'
      % encrypted_user_id
  )
else:
  print(
      'Error(s) inserting 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) inserting conversion for encrypted user ID %s.',
    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 inserted conversion for encrypted user ID %s.',
    encrypted_user_id)
end

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

אימות העיבוד של ההמרות

בדרך כלל, המערכת מעבדת את ההמרות שהועלו והן זמינות לדיווח תוך 24 שעות. כדי לוודא שההמרות שהעליתם עברו עיבוד, מומלץ להפעיל דוח חשיפות ב-Floodlight. בניגוד לדוחות אחרים של שיוך (Attribution), כברירת מחדל הדוחות האלה יחזירו גם המרות ששויכו (משויכות למודעה) וגם המרות שלא שויכו. האפשרות הזו אידיאלית לבדיקה מהירה של ההמרות ששלחתם כדי לוודא שהן הגיעו ל-Campaign Manager 360.

הערה: מומלץ לבצע בדיקות אימות באמצעות המרות מהזמן האחרון. בדוחות על חשיפות ב-Floodlight לא יופיעו המרות שנשלחו יותר מ-28 ימים אחרי חותמת הזמן שלהן.