העלאת המרות

במדריך הזה מפורטות הוראות להעלאת המרות אופליין באמצעות השירות 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 שנוצר על ידי 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 בטלוויזיה מחוברת.

השדות האופציונליים מתועדים בחומר העזר. חשוב לזכור ששדה הכמות, למרות שהוא אופציונלי, חייב להיות לפחות 1 כדי שההמרה תיכלל במדדים מסוימים (כמו 'סה"כ המרות') כשמריצים דוחות.

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

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=profile_id, id=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, או 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=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. בניגוד לדוחות שיוך אחרים, כברירת מחדל, בדוחות האלה יוצגו גם המרות שמשויכות (משויכות למודעה) וגם המרות שלא משויכות. כך אפשר לבדוק במהירות אם ההמרות ששלחתם הגיעו ל-Campaign Manager 360.

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