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 Campaign Manager 360 API. Trước khi tiếp tục, bạn nên xem Thông tin 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 lượt chuyển đổi trực tuyến và ngoại tuyến hiện có. Để làm như vậy, bạn cần cung cấp các giá trị 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 những 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 sẽ đượ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 hoạt động 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. Đây là những trường 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, gclid, dclid, matchid hoặc mobileDeviceId	Mã nhận dạng người dùng đã mã hoá, mã lượt nhấp của Google, mã lượt nhấp hiển thị, mã nhận dạng trùng khớp hoặc mã nhận dạng thiết bị di động đã tạo ra lượt chuyển đổi. Bạn không thể 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ỏ dữ liệu trùng lặp được 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 bắt đầu của hệ thống Unix.

Dưới đây là danh sách các trường có thể chỉnh sửa.

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

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

Bạn không bắt buộc phải điền thông tin vào các trường này. Giá trị sẽ không thay đổi nếu bạn không đặ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 bạn không đặ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 đưa các trường không được hỗ trợ vào yêu cầu chỉnh sửa, thì sẽ xảy ra lỗi. Nếu lượt chuyển đổi bạn đang chỉnh sửa có các giá trị đã tồn tại trước đó cho bất kỳ trường nào không được hỗ trợ, thì những giá trị đó sẽ tự động được giữ lại.

Ví dụ bên dưới minh hoạ việc tạo một đối tượng tài nguyên 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

Nêu rõ thông tin mã hoá

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

Nếu các 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á, bạn sẽ cần cung cấp thông tin chi tiết về cách mã hoá các 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 một đố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 một lệnh gọi đến batchupdate. Phương thức này chấp nhận một đố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á được liên kết (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 một cách hiệu quả nhất, thay vì cập nhật toàn bộ lô dưới dạng một 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ậ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ư bạn thấy ở trên) 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ó bất kỳ lượt chuyển đổi nào trong lô được cung cấp không thành công hay không.