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

يقدّم هذا الدليل تعليمات تفصيلية بشأن تحميل الإحالات الناجحة خارج إطار الإنترنت باستخدام خدمة Conversions API في "مدير الحملة 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) من منصة متوافقة لأجهزة التلفزيون المتّصل (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);

‫2,999

$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. كيان التشفير، وهو مجموعة فريدة من القيم المستخدَمة لتشفير أرقام تعريف المستخدمين. ترتبط هذه القيم عادةً بحساب "مدير الحملة 360" عندما يكون المصدر هو "نقل البيانات"، أو معلن "مدير الحملة 360" عندما يكون المصدر هو ماكرو %m، ولكن هذا ليس صحيحًا دائمًا. إذا لم تكن متأكدًا من الإجابة، يُرجى التواصل مع ممثل حسابك على "مدير الحملة 360" أو فريق دعم "مدير الحملة 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);

‫2,999

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

‫2,999

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

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

‫2,999

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 يومًا من الطابع الزمني المحدّد لها.