העלאת המרות

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

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

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

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

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

שדה	תיאור
encryptedUserId	מזהה משתמש מוצפן אחד שהתקבל ממאקרו תואם%m או מהעברת נתונים.
encryptedUserIdCandidates[]	רשימה של מזהי משתמשים מוצפנים שהתקבלו ממאקרו תואם%m או מהעברת נתונים. המערכת תשתמש באחד מהמזהים הראשונים עם חשיפה מתועדת ב-Floodlight לפני timestampMicros. אם אף אחד מהמזהים לא תואם לחשיפה קיימת, המערכת תשלים שגיאה.
dclid	מזהה קליק ב-Display שנוצר על ידי 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. בניגוד לדוחות שיוך (Attribution) אחרים, כברירת מחדל, הערכים האלה מיוחסים להמרות שמשויכות (שמשויכות למודעה) וגם להמרות ללא שיוך. כך תוכלו לבדוק במהירות אם ההמרות ששלחתם הגיעו ל-Campaign Manager 360.

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