Chỉnh sửa chuyển đổi

Hướng dẫn này cung cấp thông tin chi tiết về cách chỉnh sửa lượt chuyển đổi bằng dịch vụ Conversions của Campaign Manager 360 API. Trước khi tiếp tục, bạn nên xem phần Tổng quan để biết thông tin giới thiệu về lượt chuyển đổi ngoại tuyến và làm quen với các khái niệm được thảo luận trong hướng dẫn này.

Trước khi bắt đầu

Quy trình chỉnh sửa này cho phép bạn sửa đổi quantity và value của các lượt chuyển đổi trực tuyến và ngoại tuyến hiện có. Để làm việc này, bạn cần cung cấp các giá trị giúp xác định duy nhất những lượt chuyển đổi cần chỉnh sửa. Tuỳ thuộc vào loại lượt chuyển đổi mà bạn đang chỉnh sửa, bạn sẽ nhận được các giá trị này theo nhiều cách:

• Bạn có thể lấy các giá trị cần thiết để xác định lượt chuyển đổi trực tuyến từ tính năng Chuyển dữ liệu.

• Các giá trị cần thiết để xác định lượt chuyển đổi ngoại tuyến được trả về trong ConversionsBatchInsertResponse của các yêu cầu batchinsert thành công.

Sau khi bạn chỉnh sửa thành công một lượt chuyển đổi thuộc một trong hai loại, ConversionsBatchUpdateResponse sẽ chứa các giá trị cần thiết để thực hiện các lần chỉnh sửa tiếp theo.

Định cấu hình tài nguyên lượt chuyển đổi

Bước đầu tiên trong quy trình chỉnh sửa là tạo một hoặc nhiều đối tượng tài nguyên Conversion.

Các trường sau đây được dùng để xác định một lượt chuyển đổi cần chỉnh sửa. Các trường này là bắt buộc và phải khớp chính xác với một lượt chuyển đổi hiện có.

Trường	Mô tả
encryptedUserId hoặc gclid hoặc dclid hoặc matchid hoặc mobileDeviceId	Mã nhận dạng người dùng, Mã lượt nhấp của Google, Mã lượt nhấp trên Mạng Hiển thị, mã nhận dạng để so khớp hoặc mã thiết bị di động đã mã hoá tạo ra lượt chuyển đổi. Không thể sử dụng trường encryptedUserIdCandidates để chỉnh sửa.
floodlightActivityId	Hoạt động Floodlight được phân bổ lượt chuyển đổi.
floodlightConfigurationId	Cấu hình Floodlight mà hoạt động được chỉ định sử dụng.
ordinal	Giá trị nhận dạng loại bỏ trùng lặp liên kết với lượt chuyển đổi.
timestampMicros	Dấu thời gian của lượt chuyển đổi, tính bằng micrô giây kể từ thời gian Unix.

Các trường có thể chỉnh sửa được liệt kê bên dưới.

Đây là các trường bắt buộc và giá trị bạn cung cấp sẽ ghi đè mọi giá trị hiện có trong lượt chuyển đổi đang được chỉnh sửa.

Trường	Mô tả
quantity	Số lượng mặt hàng liên quan đến lượt chuyển đổi.
value	Số tiền doanh thu tạo ra từ lượt chuyển đổi.

Các trường này không bắt buộc. Giá trị sẽ không thay đổi nếu không được đặt.

Trường	Mô tả
customVariables	Biến floodlight tuỳ chỉnh của lượt chuyển đổi. Sẽ cập nhật hoặc chèn giá trị nếu biến được đặt. Giá trị của biến sẽ không thay đổi nếu không được đặt.

Tất cả các trường khác được đề cập trong tài liệu tham khảo đều không được hỗ trợ và không thể sửa đổi. Nếu bạn thêm các trường không được hỗ trợ vào yêu cầu chỉnh sửa, thì hệ thống sẽ báo lỗi. Nếu lượt chuyển đổi đang được chỉnh sửa có chứa các giá trị hiện có cho bất kỳ trường nào không được hỗ trợ, thì các giá trị đó sẽ tự động được giữ nguyên.

Ví dụ bên dưới minh hoạ cách tạo một đối tượng tài nguyên lượt chuyển đổi đơn giản để chỉnh sửa:

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

Chỉ định thông tin mã hoá

Lưu ý: Mục này chỉ áp dụng khi bạn chỉnh sửa những lượt chuyển đổi có chứa encryptedUserId.

Nếu những lượt chuyển đổi đang được chỉnh sửa có liên kết với mã nhận dạng người dùng đã mã hoá, thì bạn cần cung cấp thông tin chi tiết về cách mã hoá những lượt chuyển đổi đó trong yêu cầu chỉnh sửa. Hãy tham khảo hướng dẫn Tải lượt chuyển đổi lên để biết thông tin chi tiết.

Khi cần, việc tạo đối tượng EncryptionInfo chỉ định các giá trị này là bước thứ hai trong quy trình chỉnh sửa:

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

Tạo yêu cầu cập nhật

Bước cuối cùng trong quy trình này là chỉnh sửa lượt chuyển đổi bằng lệnh gọi đến batchupdate. Phương thức này chấp nhận đối tượng ConversionsBatchUpdateRequest, kết hợp tập hợp các lượt chuyển đổi cần chỉnh sửa với thông tin mã hoá liên quan (khi cần):

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)

Xin lưu ý rằng Campaign Manager 360 sẽ cố gắng chỉnh sửa từng lượt chuyển đổi trong yêu cầu của bạn trên cơ sở nỗ lực tối đa, thay vì cập nhật toàn bộ lô dưới dạng giao dịch tất cả hoặc không có gì. Nếu một số lượt chuyển đổi trong một lô không cập nhật được, thì những lượt chuyển đổi khác vẫn có thể được cập nhật thành công. Do đó, bạn nên kiểm tra ConversionsBatchUpdateResponse được trả về để xác định trạng thái của từng lượt chuyển đổi:

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

Trường status của phản hồi (như đã thấy trước đó) sẽ chứa một đối tượng ConversionStatus cho mỗi lượt chuyển đổi có trong yêu cầu ban đầu. Nếu bạn chỉ quan tâm đến những lượt chuyển đổi không cập nhật được, thì bạn có thể sử dụng trường hasFailures để nhanh chóng xác định xem có lượt chuyển đổi nào trong lô đã cung cấp không cập nhật được hay không. Để biết hướng dẫn về cách xử lý từng mã lỗi và những lượt chuyển đổi không thành công cần thử lại (INTERNAL và NOT_FOUND), hãy xem phần Câu hỏi thường gặp.