تحميل الإحالات الناجحة

يقدّم هذا الدليل تعليمات مفصّلة لتحميل الإحالات الناجحة غير الإلكترونية باستخدام خدمة Conversions في Campaign Manager 360 API. قبل المتابعة، ننصحك بمراجعة النظرة العامة للحصول على مقدمة عن الإحالات الناجحة غير الإلكترونية والتعرّف على المفاهيم التي تمت مناقشتها في هذا الدليل.

ضبط موارد الإحالات الناجحة

تتمثّل الخطوة الأولى في عملية تحميل الإحالات الناجحة في إنشاء عنصر واحد أو أكثر من عناصر موارد Conversion. يمثّل كلّ عنصر من هذه العناصر حدث إحالة ناجحة واحدًا ويحتوي على بعض الحقول المطلوبة:

الحقل الوصف
floodlightActivityId نشاط Floodlight الذي سيتم ربط هذه الإحالة الناجحة به
floodlightConfigurationId إعدادات Floodlight التي يستخدمها النشاط المحدّد
ordinal قيمة تُستخدَم لتحديد كيفية إزالة التكرار من الإحالات الناجحة من الجهاز أو المستخدِم نفسه في اليوم نفسه. لمزيد من المعلومات، يُرجى الاطّلاع على الأسئلة الشائعة.
timestampMicros الطابع الزمني للإحالة الناجحة، بالميكروثانية منذ حقبة يونكس

بالإضافة إلى ذلك، يجب أن يحتوي كل عنصر على واحد من الحقول التالية:

الحقل الوصف
encryptedUserId رقم تعريف مستخدم مشفّر واحد تم الحصول عليه من وحدة ماكرو المطابقة ‎%m أو نقل البيانات.
encryptedUserIdCandidates[] قائمة بأرقام تعريف المستخدمين المشفّرة التي تم الحصول عليها من وحدة ماكرو المطابقة%m أو نقل البيانات. سيتم استخدام أول رقم تعريف من أرقام التعريف هذه يتضمّن ظهورًا مسجَّلاً لإعلان Floodlight قبل timestampMicros المحدّد. إذا لم يتطابق أي من أرقام التعريف مع تعرّض حالي، سيظهر خطأ.
dclid يشمل الحقل معرّف النقرة للعرض الذي تُنشئه خدمة "مدير الحملة 360" أو "مساحة العرض والفيديو 360".
gclid يشمل الحقل معرّف النقرة من Google الذي تنشئه "إعلانات Google" أو "إعلانات شبكة البحث 360".
matchId يشمل الحقل معرّفًا فريدًا أنشأه المعلِن وتم نقله إلى "مدير الحملة 360" من خلال علامة Floodlight.
mobileDeviceId يشمل بيانات تعريف رقمية غير مشفّرة بتنسيق "معرّف المعلِنين" (IDFA) أو "المعرّف الإعلاني" (AdID) أو معرّف تلفزيون متّصل لـ "معرّف الإعلانات" (IFA) من نظام أساسي متوافق لجهاز التلفزيون المتّصل (CTV) ‏(Roku أو Fire TV أو Android TV أو Apple TV أو Xbox أو Samsung أو Vizio).

أخيرًا، لكل إحالة ناجحة مقياسان:

الحقل الوصف
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;

جافا

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
)

تحديد معلومات التشفير

إذا كنت تخطط لتحديد مصدر الإحالات الناجحة غير الإلكترونية على أنّه أرقام تعريف المستخدمين المشفّرة، كما في المثال السابق، ستحتاج إلى تقديم بعض التفاصيل حول كيفية تشفيرها كجزء من طلب الإدراج. وعلى وجه الخصوص، عليك معرفة ما يلي:

  1. مصدر التشفير، الذي يصف مصدر مجموعة من أرقام التعريف المشفّرة. القيم المقبولة هي AD_SERVING لأرقام التعريف التي يتم الحصول عليها من ماكرو المطابقة %m، أو DATA_TRANSFER لأرقام التعريف التي يتم الحصول عليها من ملفات "نقل البيانات".

  2. كيان التشفير، وهو مجموعة فريدة من القيم المستخدَمة لتشفير أرقام تعريف المستخدمين ترتبط هذه القيم عادةً بحساب على "مدير الحملة 360" عندما يكون المصدر هو "نقل البيانات"، أو بمعلِن على "مدير الحملة 360" عندما يكون المصدر هو الماكرو ‎ %m، ولكن ليس دائمًا. إذا لم تكن متأكدًا، يُرجى التواصل مع ممثل حسابك على "مدير الحملة 360" أو فريق دعم "مدير الحملة 360" لمزيد من المعلومات.

عند الضرورة، يكون إنشاء عنصر EncryptionInfo يحدّد هذه القيم هو الخطوة الثانية في عملية تحميل الإحالات الناجحة:

#C

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

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

جافا

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)

يُرجى العِلم أنّ "مدير الحملة 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);
  }
}

جافا

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 لتحديد ما إذا كانت أي إحالة ناجحة في الدفعة المقدَّمة قد تعذّر إدراجها. للحصول على إرشادات حول كيفية التعامل مع كل رمز خطأ والإحالات الناجحة التي تعذّر إجراؤها والتي يجب إعادة محاولة إجرائها (INTERNAL وNOT_FOUND)، يُرجى الاطّلاع على الأسئلة الشائعة.

التحقّق من معالجة الإحالات الناجحة

ستتم معالجة الإحالات الناجحة التي تم تحميلها وستكون متاحة لإعداد التقارير عنها في غضون 24 ساعة بشكل عام. للتحقّق مما إذا تمت معالجة الإحالات الناجحة التي حمّلتها، ننصحك بإعداد تقرير مرات ظهور Floodlight. على عكس تقارير تحديد المصدر الأخرى، ستعرض هذه التقارير تلقائيًا كلاً من الإحالات الناجحة المنسوبة (المرتبطة بإعلان) وغير المنسوبة. وهذا يجعلها مثالية للتحقّق بسرعة لمعرفة ما إذا كانت الإحالات الناجحة التي أرسلتها قد وصلت إلى "مدير الحملة 360".