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

Hướng dẫn này cung cấp hướng dẫn chi tiết về cách chỉnh sửa lượt chuyển đổi bằng dịch vụ Conversions của API Campaign Manager 360. Trước khi tiếp tục, bạn nên xem lại phần Tổng quan để tìm hiể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 như vậ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 này, 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 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 dùng để xác định lượt chuyển đổi cần chỉnh sửa. Đây là những trường bắt buộc và phải chính xác khớp 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ã hoá, mã lượt nhấp của Google, mã lượt nhấp trên Mạng Hiển thị, mã đối sánh hoặc mã thiết bị di động đã 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 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ị hiện 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 mà lượt chuyển đổi tạo ra.

Các trường này là không bắt buộc. Giá trị này 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 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 thêm các trường không được hỗ trợ vào yêu cầu chỉnh sửa, hệ thống sẽ báo lỗi. Nếu lượt chuyển đổi đang được chỉnh sửa chứa các giá trị có sẵn 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 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 ý: Phần này chỉ áp dụng khi chỉnh sửa lượt chuyển đổi chứa 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á, thì bạn cần cung cấp thông tin chi tiết về cách mã hoá các mã nhận dạng đó 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êm 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 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 theo 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 toàn bộ hoặc không. Nếu một số lượt chuyển đổi trong một lô không cập nhật được, thì các 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ư đã 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, 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ô được cung cấp không cập nhật được hay không.