تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

قبل البدء

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

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

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

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

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

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

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

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

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

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

Java

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

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]
)

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

الخطوة الأخيرة في هذه العملية هي تعديل الإحالات الناجحة من خلال مكالمة إلى 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();

Java

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

Java

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