Tải lên chuyển đổi

Quan trọng: Nâng cấp quy trình lượt chuyển đổi ngoại tuyến lên Data Manager API để cải thiện trải nghiệm của nhà phát triển và sử dụng các tính năng bổ sung. Bạn không nên triển khai quy trình mới cho lượt chuyển đổi ngoại tuyến bằng Campaign Manager 360 API.

Hướng dẫn này cung cấp thông tin chi tiết về cách tải lượt chuyển đổi ngoại tuyến lên bằng dịch vụ Conversions của Campaign Manager 360 API. Trước khi tiếp tục, bạn nên xem lại 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.

Lưu ý: Mặc dù API hỗ trợ lượt chuyển đổi ngoại tuyến cho Campaign Manager 360 và Display & Video 360, nhưng Dữ liệu giỏ hàng không được cung cấp cho cả hai sản phẩm đó. Tìm hiểu thêm về Dữ liệu giỏ hàng.

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

Bước đầu tiên trong quy trình tải lượt chuyển đổi lên là tạo một hoặc nhiều đối tượng tài nguyên Conversion. Mỗi đối tượng này đại diện cho một sự kiện chuyển đổi và chứa một vài trường bắt buộc:

Trường	Mô tả
floodlightActivityId	Hoạt động Floodlight mà lượt chuyển đổi này sẽ được liên kết.
floodlightConfigurationId	Cấu hình Floodlight mà hoạt động được chỉ định sử dụng.
ordinal	Giá trị dùng để kiểm soát cách loại bỏ lượt chuyển đổi trùng lặp từ cùng một thiết bị hoặc người dùng trong cùng một ngày. Hãy xem phần Câu hỏi thường gặp để biết thêm thông tin.
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.

Ngoài ra, mỗi đối tượng phải chứa một trong các trường sau:

Trường	Mô tả
encryptedUserId	Một mã nhận dạng người dùng đã mã hoá duy nhất lấy được từ macro so khớp%m hoặc Chuyển dữ liệu.
encryptedUserIdCandidates[]	Danh sách mã nhận dạng người dùng đã mã hoá có được từ macro khớp%m hoặc Chuyển dữ liệu. Mã nhận dạng đầu tiên trong số các mã nhận dạng này có lượt hiển thị Floodlight được ghi lại trước timestampMicros được chỉ định sẽ được sử dụng. Nếu không có mã nhận dạng nào khớp với một lượt hiển thị hiện có, thì hệ thống sẽ gửi một lỗi.
dclid	Mã lượt nhấp trên Mạng Hiển thị do Campaign Manager 360 hoặc Display & Video 360 tạo.
gclid	Mã lượt nhấp của Google do Google Ads hoặc Search Ads 360 tạo.
matchId	Giá trị nhận dạng riêng biệt do nhà quảng cáo tạo được truyền đến Campaign Manager 360 thông qua thẻ Floodlight.
mobileDeviceId	Mã thiết bị di động chưa mã hoá ở định dạng IDFA hay Mã nhận dạng cho quảng cáo (AdID) hoặc Mã nhận dạng cho quảng cáo (IFA) trên TV có kết nối Internet từ nền tảng thiết bị CTV được hỗ trợ (Roku, Fire TV, Android TV, Apple TV, Xbox, Samsung, Vizio).

Cuối cùng, mỗi lượt chuyển đổi có hai chỉ số:

Trường	Mô tả
quantity	Bắt buộc. Số lượng mặt hàng liên quan đến lượt chuyển đổi. Giá trị này phải ít nhất là 1 để lượt chuyển đổi được tính vào một số chỉ số nhất định (chẳng hạn như Tổng số lượt chuyển đổi).
value	Số tiền liên quan đến lượt chuyển đổi. Được diễn giải theo đơn vị tiền tệ của nhà quảng cáo sở hữu cấu hình Floodlight.

Các trường không bắt buộc được ghi lại trong tài liệu tham khảo.

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:

C#

// Generate a timestamp in milliseconds since Unix epoch.
TimeSpan timeSpan = DateTime.UtcNow - new DateTime(1970, 1, 1);
long currentTimeInMilliseconds = (long) timeSpan.TotalMilliseconds;

// Find the Floodlight configuration ID based on the provided activity ID.
FloodlightActivity floodlightActivity =
    service.FloodlightActivities.Get(profileId, floodlightActivityId).Execute();
long floodlightConfigurationId = (long) floodlightActivity.FloodlightConfigurationId;

// Create the conversion.
Conversion conversion = new Conversion();
conversion.EncryptedUserId = conversionUserId;
conversion.FloodlightActivityId = floodlightActivityId;
conversion.FloodlightConfigurationId = floodlightConfigurationId;
conversion.Ordinal = currentTimeInMilliseconds.ToString();
conversion.TimestampMicros = currentTimeInMilliseconds * 1000;

Java

long currentTimeInMilliseconds = System.currentTimeMillis();

// Find Floodlight configuration ID based on the provided activity ID.
FloodlightActivity floodlightActivity = reporting.floodlightActivities()
    .get(profileId, floodlightActivityId).execute();
long floodlightConfigurationId = floodlightActivity.getFloodlightConfigurationId();

Conversion conversion = new Conversion();
conversion.setEncryptedUserId(encryptedUserId);
conversion.setFloodlightActivityId(floodlightActivityId);
conversion.setFloodlightConfigurationId(floodlightConfigurationId);
conversion.setOrdinal(String.valueOf(currentTimeInMilliseconds));
conversion.setTimestampMicros(currentTimeInMilliseconds * 1000);

PHP

$currentTimeInMicros = time() * 1000 * 1000;

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

$conversion = new Google_Service_Dfareporting_Conversion();
$conversion->setEncryptedUserId($values['encrypted_user_id']);
$conversion->setFloodlightActivityId($values['floodlight_activity_id']);
$conversion->setFloodlightConfigurationId($floodlightConfigId);
$conversion->setOrdinal($currentTimeInMicros);
$conversion->setTimestampMicros($currentTimeInMicros);

Python

# Look up the Floodlight configuration ID based on activity ID.
floodlight_activity = (
    service.floodlightActivities()
    .get(profileId=str(profile_id), id=str(floodlight_activity_id))
    .execute()
)
floodlight_config_id = floodlight_activity['floodlightConfigurationId']

current_time_in_micros = int(time.time() * 1000000)

# Construct the conversion.
conversion = {
    'encryptedUserId': encrypted_user_id,
    'floodlightActivityId': floodlight_activity_id,
    'floodlightConfigurationId': floodlight_config_id,
    'ordinal': current_time_in_micros,
    'timestampMicros': current_time_in_micros
}

Ruby

# Look up the Floodlight configuration ID based on activity ID.
floodlight_activity = service.get_floodlight_activity(profile_id,
  floodlight_activity_id)
floodlight_config_id = floodlight_activity.floodlight_configuration_id

current_time_in_micros = DateTime.now.strftime('%Q').to_i * 1000

# Construct the conversion.
conversion = DfareportingUtils::API_NAMESPACE::Conversion.new(
  encrypted_user_id: encrypted_user_id,
  floodlight_activity_id: floodlight_activity_id,
  floodlight_configuration_id: floodlight_config_id,
  ordinal: current_time_in_micros,
  timestamp_micros: current_time_in_micros
)

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

Lưu ý: Phần này chỉ áp dụng khi bạn tải lên những lượt chuyển đổi có chứa encryptedUserId hoặc encryptedUserIdCandidates[].

Nếu dự định phân bổ lượt chuyển đổi ngoại tuyến cho mã nhận dạng người dùng đã mã hoá, như trong ví dụ trước, thì bạn cần cung cấp một số thông tin chi tiết về cách mã hoá mã nhận dạng người dùng trong yêu cầu chèn. Cụ thể, bạn cần biết:

1. Nguồn mã hoá, mô tả nguồn gốc của một loạt mã nhận dạng đã mã hoá. Các giá trị được chấp nhận là AD_SERVING đối với mã nhận dạng lấy từ macro so khớp %m hoặc DATA_TRANSFER đối với mã nhận dạng lấy từ tệp Chuyển dữ liệu.

2. Thực thể mã hoá, là một tập hợp các giá trị riêng biệt dùng để mã hoá mã nhận dạng người dùng. Các giá trị này thường liên quan đến một tài khoản Campaign Manager 360 khi nguồn là Chuyển dữ liệu hoặc một nhà quảng cáo Campaign Manager 360 khi nguồn là macro %m, nhưng không phải lúc nào cũng vậy. Nếu bạn không chắc chắn, hãy liên hệ với nhân viên đại diện khách hàng của Campaign Manager 360 hoặc nhóm hỗ trợ Campaign Manager 360 để biết thêm thông tin.

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 tải lượt chuyển đổi lên:

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

Xin lưu ý rằng mỗi yêu cầu chèn chỉ có thể chứa một đối tượng EncryptionInfo. Điều này có nghĩa là tất cả lượt chuyển đổi có trong một yêu cầu nhất định phải bắt nguồn từ cùng một nguồn và sử dụng cùng một thực thể mã hoá.

Tạo yêu cầu chèn

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

C#

// Insert the conversion.
ConversionsBatchInsertRequest request = new ConversionsBatchInsertRequest();
request.Conversions = new List<Conversion>() { conversion };
request.EncryptionInfo = encryptionInfo;

ConversionsBatchInsertResponse response =
    service.Conversions.Batchinsert(request, profileId).Execute();

Java

ConversionsBatchInsertRequest request = new ConversionsBatchInsertRequest();
request.setConversions(ImmutableList.of(conversion));
request.setEncryptionInfo(encryptionInfo);

ConversionsBatchInsertResponse response = reporting.conversions()
    .batchinsert(profileId, request).execute();

PHP

$batch = new Google_Service_Dfareporting_ConversionsBatchInsertRequest();
$batch->setConversions([$conversion]);
$batch->setEncryptionInfo($encryptionInfo);

$result = $this->service->conversions->batchinsert(
    $values['user_profile_id'],
    $batch
);

Python

# Insert the conversion.
request_body = {
    'conversions': [conversion],
    'encryptionInfo': encryption_info
}
request = service.conversions().batchinsert(
    profileId=str(profile_id), body=request_body
)
response = request.execute()

Ruby

# Construct the batch insert request.
batch_insert_request =
  DfareportingUtils::API_NAMESPACE::ConversionsBatchInsertRequest.new(
    conversions: [conversion],
    encryption_info: encryption_info
  )

# Insert the conversion.
result = service.batchinsert_conversion(profile_id, batch_insert_request)

Xin lưu ý rằng Campaign Manager 360 cố gắng chèn 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ì chèn 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 chèn được, thì các lượt chuyển đổi khác vẫn có thể được chèn thành công. Do đó, bạn nên kiểm tra ConversionsBatchInsertResponse đượ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 inserted conversion for encrypted user ID {0}.",
      conversionUserId);
} else {
  Console.WriteLine("Error(s) inserting 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 inserted conversion for encrypted user ID %s.%n",
      encryptedUserId);
} else {
  System.out.printf("Error(s) inserting 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 inserted conversion for encrypted user ID %s.',
        $values['encrypted_user_id']
    );
} else {
    printf(
        'Error(s) inserting 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 inserted conversion for encrypted user ID %s.'
      % encrypted_user_id
  )
else:
  print(
      'Error(s) inserting 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) inserting conversion for encrypted user ID %s.',
    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 inserted conversion for encrypted user ID %s.',
    encrypted_user_id)
end

Trường status của phản hồi 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 chèn được, thì bạn có thể sử dụng trường hasFailures để nhanh chóng xác định xem bất kỳ lượt chuyển đổi nào trong lô được cung cấp có bị lỗi 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.

Xác minh rằng các lượt chuyển đổi đã được xử lý

Lượt chuyển đổi đã tải lên thường sẽ được xử lý và có thể báo cáo trong vòng 24 giờ. Để xác minh xem lượt chuyển đổi mà bạn đã tải lên có được xử lý hay không, bạn nên chạy báo cáo Số lượt hiển thị Floodlight. Không giống như các báo cáo phân bổ khác, theo mặc định, các báo cáo này sẽ trả về cả lượt chuyển đổi được phân bổ (liên kết với một quảng cáo) và lượt chuyển đổi không được phân bổ. Điều này giúp bạn nhanh chóng kiểm tra xem các lượt chuyển đổi mà bạn đã gửi có được chuyển đến Campaign Manager 360 hay không.

Lưu ý: Bạn nên thực hiện quy trình kiểm tra xác minh bằng các lượt chuyển đổi gần đây. Báo cáo Số lượt hiển thị Floodlight sẽ không phản ánh những lượt chuyển đổi được gửi sau dấu thời gian của chúng hơn 28 ngày.