Hướng dẫn này cung cấp hướng dẫn chi tiết về cách tải lượt chuyển đổi ngoại tuyến lên bằng cách sử dụng dịch vụ API Campaign Manager 360 Conversions
. Trước khi
tiếp tục, bạn nên xem lại
Tổng quan để biết 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.
Định cấu hình tài nguyên 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 | Nội dung mô tả |
---|---|
floodlightActivityId |
Hoạt động Floodlight được liên kết với chuyển đổi này. |
floodlightConfigurationId |
Cấu hình Floodlight do hoạt động được chỉ định sử dụng. |
ordinal |
Giá trị được sử dụng để kiểm soát cách chuyển đổi từ cùng một thiết bị hoặc người dùng trong cùng một ngày được loại bỏ trùng lặp. Xem 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 bắt đầu của hệ thống Unix. |
Ngoài ra, mỗi đối tượng phải chứa một trong các trường sau:
Trường | Nội dung mô tả |
---|---|
encryptedUserId |
Một mã nhận dạng người dùng được mã hóa duy nhất thu được từ macro so khớp%m hoặc Chuyển dữ liệu. |
encryptedUserIdCandidates[] |
Danh sách mã người dùng được mã hóa thu được từ macro so khớp%m hoặc Chuyển dữ liệu. Mã đầu tiên trong số này có mức độ phơi sáng Floodlight được ghi lại trước timestampMicros đã chỉ định sẽ được sử dụng. Nếu không có mã nhận dạng nào khớp với thông tin hiển thị hiện có, hệ thống sẽ báo lỗi. |
dclid |
Giá trị nhận dạng lượt nhấp trên Mạng Hiển thị do Campaign Manager 360 hoặc Display & Video 360 tạo. |
gclid |
Giá trị nhận dạng lượt nhấp của Google do Google Ads hoặc Search Ads 360 tạo. |
matchId |
Giá trị nhận dạng duy nhất do nhà quảng cáo tạo đã chuyển đến Campaign Manager 360 thông qua thẻ Floodlight. |
mobileDeviceId |
Mã thiết bị di động không được mã hóa ở định dạng IDFA hoặc AdID hoặc Mã nhận dạng cho quảng cáo trên TV thông minh (IFA) từ nền tảng thiết bị CTV được hỗ trợ (Roku, Fire TV, Android TV, Apple TV, Xbox, Samsung, Vizio). Xin lưu ý rằng Google không hỗ trợ IFA cho TV thông minh. |
Bạn có thể xem các trường không bắt buộc trong tài liệu tham khảo này. Xin lưu ý rằng trường số lượng (mặc dù không bắt buộc) phải có ít nhất 1 lượt chuyển đổi thì mớ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) khi chạy báo cáo.
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:
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);
1.199
$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=profile_id, id=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ã hóa
Nếu dự định phân bổ lượt chuyển đổi ngoại tuyến cho mã người dùng được mã hoá, như trong ví dụ trước, bạn cần cung cấp một số thông tin chi tiết về cách mã hoá các lượt chuyển đổi đó trong yêu cầu chèn. Cụ thể, bạn cần phải biết:
Nguồn mã hoá, mô tả nguồn của một lô mã hoá. Giá trị được chấp nhận là
AD_SERVING
đối với mã nhận dạng có nguồn gốc từ macro so khớp %m hoặcDATA_TRANSFER
đối với mã nhận dạng có nguồn gốc từ tệp Chuyển dữ liệu.Thực thể mã hoá, là một tập hợp giá trị duy nhấ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 tài khoản Campaign Manager 360 khi nguồn là Chuyển dữ liệu hoặc nhà quảng cáo Campaign Manager 360 khi nguồn là macro %m, nhưng điều này không phải lúc nào cũng đúng. 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 bộ phận hỗ trợ của 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);
1.199
$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 có thể chỉ 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 các lượt chuyển đổi lên bằng lệnh gọi
batchinsert
. Phương thức này chấp nhận một đối tượng ConversionsBatchInsertRequest
. Đối tượng này sẽ kết hợp tập hợp lượt chuyển đổi được tải lên với thông tin mã hoá liên kết (khi cần thiết):
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();
1.199
$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=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 sẽ 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 một giao dịch hoàn toàn không có gì. Nếu không chèn được một số lượt chuyển đổi hàng loạt, bạn vẫn có thể chèn các lượt chuyển đổi khác. 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()); } }
1.199
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 phản hồi status
, 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 chỉ quan tâm đến những lượt chuyển đổi
không chèn được, bạn có thể sử dụng trường hasFailures
để nhanh chóng xác định xem lượt chuyển đổi có nào trong lô đã cung cấp không thành công hay không.
Xác minh lượt chuyển đổi đã được xử lý
Nhìn chung, các lượt chuyển đổi đã tải lên 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 bạn đã tải lên hay chưa đã được xử lý, 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, các báo cáo này sẽ trả về cả lượt chuyển đổi được phân bổ (được liên kết với quảng cáo) và lượt chuyển đổi chưa được phân bổ theo mặc định. Do đó, bạn nên kiểm tra nhanh để xem các lượt chuyển đổi mà bạn đã gửi có được đưa vào Campaign Manager 360 hay không.