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

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

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

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

تتمثل الخطوة الأولى في عملية تحميل الإحالات الناجحة في إنشاء عنصر واحد أو أكثر من عناصر موارد 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) من نظام أساسي متوافق لأجهزة التلفزيون المتّصل (Roku أو Fire TV أو Android TV أو Apple TV أو Xbox أو Samsung أو Vizio) يُرجى العِلم أنّ Google لا توفّر واجهة برمجة تطبيقات لأجهزة التلفزيون المتّصلة من 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);

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;

Java

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

Java

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

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

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