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

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

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

قبل البدء

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

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

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

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

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

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

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

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

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

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

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

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

‫2,999

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

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

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

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

‫2,999

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

‫2,999

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