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

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

ملاحظة: على الرغم من أنّ واجهة برمجة التطبيقات تتيح الإحالات الناجحة غير الإلكترونية لكلّ من "مدير الحملة 360" و"مساحة العرض والفيديو 360"، لا تتوفّر ميزة "بيانات سلة التسوّق" لأيّ من هذين المنتجين. مزيد من المعلومات عن "بيانات سلة التسوّق"

إعداد مَراجع الإحالات الناجحة

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

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

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

الحقل	الوصف
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). يُرجى العلم أنّ Google لا تتيح "معرّفات الإعلانات" (IFA) لأجهزة التلفزيون المتّصل على YouTube.

أخيرًا، تحتوي كل إحالة ناجحة على مقياسَين:

الحقل	الوصف
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=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 match، أو 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=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 لتحديد ما إذا تعذّر إدراج أي إحالة ناجحة في الدفعة المقدَّمة.

التأكّد من معالجة الإحالات الناجحة

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

ملاحظة: يجب إجراء اختبار التحقّق باستخدام الإحالات الناجحة الحديثة. لن تعكس تقارير "مرات الظهور في Floodlight" الإحالات الناجحة التي تم إرسالها بعد أكثر من 28 يومًا من الطابع الزمني.