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

يوفّر هذا الدليل تعليمات مفصّلة لتحميل الإحالات الناجحة غير الإلكترونية باستخدام خدمة 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).

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

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

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

ملاحظة: ينطبق هذا القسم فقط عند تحميل الإحالات الناجحة التي تحتوي على encryptedUserId أو encryptedUserIdCandidates[].

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

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

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

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

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