تعديل الإحالات الناجحة

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

قبل البدء

تسمح لك عملية تعديل سير العمل هذه بتعديل quantity وvalue للإحالات الناجحة الحالية على الإنترنت وخارجه. لإجراء ذلك، عليك تقديم قيم تحدّد الإحالات الناجحة التي سيتم تعديلها بشكلٍ فريد. استنادًا إلى نوع الإحالات الناجحة التي تعدّلها، ستحصل على هذه القيم بطرق مختلفة:

  • يمكن الحصول على القيم اللازمة لتحديد الإحالات الناجحة على الإنترنت من نقل البيانات.

  • يتم عرض القيم اللازمة لتحديد الإحالات الناجحة غير الإلكترونية في ConversionsBatchInsertResponse لطلبات batchinsert الناجحة.

بعد تعديل إحالة ناجحة من أيّ من النوعَين بنجاح، سيحتوي ConversionsBatchUpdateResponse على القيم اللازمة لإجراء تعديلات لاحقة.

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

تتضمّن الخطوة الأولى في سير عمل التعديل إنشاء عنصر واحد أو أكثر من عناصر موارد Conversion.

تُستخدَم الحقول التالية لتحديد إحالة ناجحة لتعديلها. هذه الحقول مطلوبة ويجب أن تتطابق تمامًا مع إحالة ناجحة حالية.

الحقل الوصف

encryptedUserId أو gclid أو dclid أو matchid أو mobileDeviceId

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

في ما يلي قائمة بالحقول التي يمكن تعديلها.

هذه الحقول مطلوبة، وستحلّ القيم التي تقدّمها محلّ أي قيم سبق أن تمّ إدخالها في الإحالة الناجحة التي يتمّ تعديلها.

الحقل الوصف
quantity عدد السلع المرتبطة بالإحالة الناجحة
value مبلغ الأرباح المحقَّقة من الإحالة الناجحة.

هذه الحقول اختيارية. ستظل القيمة بدون تغيير إذا لم يتم ضبطها.

الحقل الوصف
customVariables متغيّرات Floodlight المخصّصة للإحالة الناجحة. سيتم تعديل القيمة أو إدراجها إذا تم ضبط المتغيّر. لا تتغيّر قيمة المتغيّر إذا لم يتم ضبطها.

جميع الحقول الأخرى المذكورة في المستندات المرجعية غير متوافقة ولا يمكن تعديلها. سيؤدي تضمين حقول غير متوافقة في طلب التعديل إلى حدوث خطأ. إذا كانت الإحالة الناجحة التي يتم تعديلها تحتوي على قيم حالية لأي حقول غير متوافقة، سيتم الاحتفاظ بهذه القيم تلقائيًا.

يوضّح المثال أدناه كيفية إنشاء عنصر بسيط لمورد الإحالة الناجحة لتعديله:

#C

// Find the Floodlight configuration ID based on the provided activity ID.
FloodlightActivity floodlightActivity =
    service.FloodlightActivities.Get(profileId, floodlightActivityId).Execute();
long floodlightConfigurationId = (long) floodlightActivity.FloodlightConfigurationId;

// Construct the conversion object with values that identify the conversion to update.
Conversion conversion = new Conversion();
conversion.EncryptedUserId = conversionUserId;
conversion.FloodlightActivityId = floodlightActivityId;
conversion.FloodlightConfigurationId = floodlightConfigurationId;
conversion.Ordinal = conversionOrdinal;
conversion.TimestampMicros = conversionTimestamp;

// Set the fields to be updated. These fields are required; to preserve a value from the
// existing conversion, it must be copied over manually.
conversion.Quantity = newQuantity;
conversion.Value = newValue;

جافا

// Create a conversion object populated with values that identify the conversion to update.
Conversion conversion = new Conversion();
conversion.setEncryptedUserId(encryptedUserId);
conversion.setFloodlightActivityId(floodlightActivityId);
conversion.setFloodlightConfigurationId(floodlightConfigurationId);
conversion.setOrdinal(ordinal);
conversion.setTimestampMicros(timestampMicros);

// Set the fields to be updated. These fields are required; to preserve a value from the
// existing conversion, it must be copied over manually.
conversion.setQuantity(newQuantity);
conversion.setValue(newValue);

PHP

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

// Create a conversion object with values that identify the conversion to
// update.
$conversion = new Google_Service_Dfareporting_Conversion();
$conversion->setEncryptedUserId($values['encrypted_user_id']);
$conversion->setFloodlightActivityId($values['floodlight_activity_id']);
$conversion->setFloodlightConfigurationId($floodlightConfigId);
$conversion->setOrdinal($values['ordinal']);
$conversion->setTimestampMicros($values['timestamp']);

// Set the fields to be updated. These fields are required; to preserve a
// value from the existing conversion, it must be copied over manually.
$conversion->setQuantity($values['new_quantity']);
$conversion->setValue($values['new_value']);

Python

# Construct the conversion object with values that identify the conversion
# to update.
conversion = {
    'encryptedUserId': encrypted_user_id,
    'floodlightActivityId': floodlight_activity_id,
    'floodlightConfigurationId': floodlight_config_id,
    'ordinal': ordinal,
    'timestampMicros': timestamp
}

# Set the fields to be updated. These fields are required; to preserve a
# value from the existing conversion, it must be copied over manually.
conversion['quantity'] = new_quantity
conversion['value'] = new_value

Ruby

# Look up the Floodlight configuration ID based on activity ID.
floodlight_activity = service.get_floodlight_activity(profile_id,
  existing_conversion[:floodlight_activity_id])
floodlight_config_id = floodlight_activity.floodlight_configuration_id

# Construct the conversion with values that identify the conversion to
# update.
conversion = DfareportingUtils::API_NAMESPACE::Conversion.new(
  encrypted_user_id: existing_conversion[:encrypted_user_id],
  floodlight_activity_id: existing_conversion[:floodlight_activity_id],
  floodlight_configuration_id: floodlight_config_id,
  ordinal: existing_conversion[:ordinal],
  timestamp_micros: existing_conversion[:timestamp]
)

# Set the fields to be updated. These fields are required; to preserve a
# value from the existing conversion, it must be copied over manually.
conversion.quantity = new_quantity
conversion.value = new_value

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

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

عند الضرورة، يكون إنشاء عنصر 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]
)

إنشاء طلب تعديل

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

#C

// Insert the conversion.
ConversionsBatchUpdateRequest request = new ConversionsBatchUpdateRequest();
request.Conversions = new List<Conversion>() { conversion };
request.EncryptionInfo = encryptionInfo;

ConversionsBatchUpdateResponse response =
    service.Conversions.Batchupdate(request, profileId).Execute();

جافا

ConversionsBatchUpdateRequest request = new ConversionsBatchUpdateRequest();
request.setConversions(ImmutableList.of(conversion));
request.setEncryptionInfo(encryptionInfo);

ConversionsBatchUpdateResponse response = reporting.conversions()
    .batchupdate(profileId, request).execute();

PHP

$batch = new Google_Service_Dfareporting_ConversionsBatchUpdateRequest();
$batch->setConversions([$conversion]);
$batch->setEncryptionInfo($encryptionInfo);

$result = $this->service->conversions->batchupdate(
    $values['user_profile_id'],
    $batch
);

Python

# Update the conversion.
request_body = {
    'conversions': [conversion],
    'encryptionInfo': encryption_info
}
request = service.conversions().batchupdate(
    profileId=profile_id, body=request_body)
response = request.execute()

Ruby

# Construct the batch update request.
batch_update_request =
  DfareportingUtils::API_NAMESPACE::ConversionsBatchUpdateRequest.new(
    conversions: [conversion],
    encryption_info: encryption_info
  )

# Update the conversion.
result = service.batchupdate_conversion(profile_id, batch_update_request)

يُرجى العِلم أنّ "مدير الحملة 360" يحاول تعديل كل إحالة ناجحة في طلبك بأفضل طريقة ممكنة، بدلاً من تعديل المجموعة بأكملها كعملية شاملة. إذا تعذّر تعديل بعض الإحالات الناجحة في مجموعة، قد يظلّ من الممكن تعديل الإحالات الأخرى بنجاح. لذلك، ننصحك بفحص ConversionsBatchUpdateResponse الذي تم إرجاعه لتحديد حالة كل إحالة ناجحة:

#C

// Handle the batchinsert response.
if (!response.HasFailures.Value) {
  Console.WriteLine("Successfully updated conversion for encrypted user ID {0}.",
      conversionUserId);
} else {
  Console.WriteLine("Error(s) updating 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 updated conversion for encrypted user ID %s.%n",
      encryptedUserId);
} else {
  System.out.printf("Error(s) updating 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 updated conversion for encrypted user ID %s.',
        $values['encrypted_user_id']
    );
} else {
    printf(
        'Error(s) updating 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 updated conversion for encrypted user ID %s.' %
        encrypted_user_id)
else:
  print('Error(s) updating 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) updating conversion for encrypted user ID %s.',
    existing_conversion[: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 updated conversion for encrypted user ID %s.',
    existing_conversion[:encrypted_user_id])
end

سيحتوي الحقل status في الردّ، كما هو موضّح أعلاه، على كائن ConversionStatus لكلّ إحالة ناجحة مضمّنة في الطلب الأصلي. إذا كنت مهتمًا فقط بالإحالات الناجحة التي لم يتم تعديلها، يمكن استخدام الحقل hasFailures لتحديد ما إذا كانت أي إحالة ناجحة في المجموعة المقدَّمة قد تعذّر تعديلها.