تبدیل ها را آپلود کنید

این راهنما دستورالعمل‌های دقیقی را برای آپلود تبدیل‌های آفلاین با استفاده از سرویس Conversions API Campaign Manager 360 ارائه می‌کند. قبل از ادامه، توصیه می شود برای آشنایی با تبدیل های آفلاین و آشنایی با مفاهیم مطرح شده در این راهنما، مرور کلی را مرور کنید.

توجه: در حالی که API از تبدیل‌های آفلاین برای Campaign Manager 360 و Display & Video 360 پشتیبانی می‌کند، اطلاعات سبد خرید برای هیچ یک از این محصولات در دسترس نیست. درباره داده های سبد خرید بیشتر بیاموزید.

پیکربندی منابع تبدیل

اولین مرحله در فرآیند آپلود تبدیل، ایجاد یک یا چند شی منبع Conversion است. هر یک از این اشیاء نشان دهنده یک رویداد تبدیل واحد است و شامل چند فیلد ضروری است:

میدان	توضیحات
floodlightActivityId	فعالیت Floodlight که این تبدیل با آن مرتبط خواهد بود.
floodlightConfigurationId	پیکربندی Floodlight که توسط فعالیت مشخص شده استفاده می شود.
ordinal	مقداری که برای کنترل نحوه کپی کردن تبدیل‌های یک دستگاه یا کاربر در همان روز استفاده می‌شود. برای اطلاعات بیشتر به سوالات متداول مراجعه کنید.
timestampMicros	مهر زمانی تبدیل، در میکروثانیه از دوران یونیکس.

علاوه بر این، هر شی باید دارای یکی از فیلدهای زیر باشد:

میدان	توضیحات
encryptedUserId	یک شناسه کاربر رمزگذاری شده منفرد که از %m ماکرو مطابقت یا انتقال داده به دست آمده است.
encryptedUserIdCandidates[]	فهرستی از شناسه‌های کاربر رمزگذاری‌شده به‌دست‌آمده از %m ماکرو مطابقت یا انتقال داده . اولین مورد از این شناسه‌ها با نوردهی ثبت شده قبل از timestampMicros مشخص شده Micros استفاده خواهد شد. اگر هیچ یک از شناسه‌ها با نوردهی موجود مطابقت نداشته باشد، خطایی ایجاد می‌شود.
dclid	یک شناسه کلیک نمایشی که توسط Campaign Manager 360 یا Display & Video 360 ایجاد شده است.
gclid	یک شناسه کلیک گوگل که توسط Google Ads یا Search Ads 360 ایجاد شده است.
matchId	یک تبلیغ‌کننده منحصربه‌فرد، شناسه‌ای ایجاد کرد که از طریق یک برچسب Floodlight به Campaign Manager 360 ارسال شد.
mobileDeviceId	یک شناسه تلفن همراه رمزگذاری نشده در قالب IDFA یا AdID یا یک شناسه تلویزیون متصل برای تبلیغات (IFA) از یک پلت فرم دستگاه CTV پشتیبانی شده (Roku، Fire TV، Android TV، Apple TV، Xbox، Samsung، Vizio). توجه داشته باشید که Google از IFAهای تلویزیون متصل YouTube پشتیبانی نمی کند.

فیلدهای اختیاری در مستندات مرجع مستند شده اند. توجه داشته باشید که فیلد کمیت، اگرچه اختیاری است، باید حداقل 1 باشد تا هنگام اجرای گزارش‌ها، تبدیل در معیارهای خاصی (مانند کل تبدیل‌ها) لحاظ شود.

مثال زیر ایجاد یک شی منبع تبدیل ساده را نشان می دهد:

سی شارپ

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

جاوا

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

پایتون

# 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
}

یاقوت سرخ

# 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 که این مقادیر را مشخص می کند، دومین مرحله در فرآیند آپلود تبدیل است:

سی شارپ

// Create the encryption info.
EncryptionInfo encryptionInfo = new EncryptionInfo();
encryptionInfo.EncryptionEntityId = encryptionEntityId;
encryptionInfo.EncryptionEntityType = encryptionEntityType;
encryptionInfo.EncryptionSource = encryptionSource;

جاوا

// 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']);

پایتون

# Construct the encryption info.
encryption_info = {
    'encryptionEntityId': encryption_entity_id,
    'encryptionEntityType': encryption_entity_type,
    'encryptionSource': encryption_source
}

یاقوت سرخ

# 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 را می‌پذیرد که مجموعه تبدیل‌هایی را که باید آپلود شوند با اطلاعات رمزگذاری مرتبط با آنها ترکیب می‌کند (در صورت لزوم):

سی شارپ

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

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

جاوا

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

پایتون

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

یاقوت سرخ

# 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 برگشتی را بررسی کنید:

سی شارپ

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

جاوا

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

پایتون

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'])

یاقوت سرخ

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 Impressions تبدیل‌هایی را که بیش از ۲۸ روز پس از مهر زمانی ارسال شده‌اند منعکس نمی‌کنند.