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

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

قبل البدء

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

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