Panduan ini memberikan petunjuk mendetail untuk mengupload konversi offline menggunakan layanan Conversions
Campaign Manager 360 API. Sebelum
melanjutkan, sebaiknya Anda meninjau
Ringkasan untuk mengetahui pengantar konversi offline dan
untuk memahami konsep yang dibahas dalam panduan ini.
Konfigurasikan resource konversi
Langkah pertama dalam proses upload konversi adalah membuat satu atau beberapa
objek resource Conversion
. Setiap objek ini
mewakili satu peristiwa konversi dan berisi beberapa kolom wajib diisi:
Kolom | Deskripsi |
---|---|
floodlightActivityId |
Aktivitas Floodlight yang akan dikaitkan dengan konversi ini. |
floodlightConfigurationId |
Konfigurasi Floodlight yang digunakan oleh aktivitas yang ditentukan. |
ordinal |
Nilai yang digunakan untuk mengontrol cara konversi dari perangkat atau pengguna yang sama dihapus pada hari yang sama. Lihat FAQ untuk informasi selengkapnya. |
timestampMicros |
Stempel waktu konversi, dalam mikrodetik sejak epoch Unix. |
Selain itu, setiap objek harus berisi salah satu kolom berikut:
Kolom | Deskripsi |
---|---|
encryptedUserId |
Satu ID pengguna terenkripsi yang diperoleh dari makro pencocokan%m atau Transfer Data. |
encryptedUserIdCandidates[] |
Daftar ID pengguna terenkripsi yang diperoleh dari makro pencocokan kecocokan%m atau Transfer Data. ID pertama dengan eksposur Floodlight yang direkam sebelum timestampMicros yang ditentukan akan digunakan. Jika tidak ada ID yang cocok dengan eksposur yang ada, error akan ditampilkan. |
dclid |
ID klik Display yang dihasilkan oleh Campaign Manager 360 atau Display & Video 360. |
gclid |
ID Klik Google yang dibuat oleh Google Ads atau Search Ads 360. |
matchId |
ID unik yang dibuat pengiklan yang diteruskan ke Campaign Manager 360 melalui tag Floodlight. |
mobileDeviceId |
ID seluler yang tidak dienkripsi dalam format IDFA atau ID iklan atau ID TV yang Terhubung untuk Iklan (IFA) dari platform perangkat CTV yang didukung (Roku, Fire TV, Android TV, Apple TV, Xbox, Samsung, Vizio). Perhatikan bahwa Google tidak mendukung IFA YouTube Connected TV. |
Kolom opsional didokumentasikan dalam dokumentasi referensi. Perhatikan bahwa kolom kuantitas, meskipun opsional, harus setidaknya 1 agar konversi diperhitungkan dalam metrik tertentu (seperti Total Konversi) saat menjalankan laporan.
Contoh di bawah ini menggambarkan pembuatan objek resource konversi sederhana:
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=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 )
Menentukan info enkripsi
Jika Anda berencana untuk mengatribusikan konversi offline ke ID pengguna terenkripsi, seperti dalam contoh sebelumnya, Anda harus memberikan beberapa detail tentang cara ID enkripsi dienkripsi sebagai bagian dari permintaan penyisipan Anda. Khususnya, Anda perlu mengetahui:
Sumber enkripsi, yang menjelaskan asal batch ID terenkripsi. Nilai yang dapat diterima adalah
AD_SERVING
untuk ID yang bersumber dari makro pencocokan %m, atauDATA_TRANSFER
untuk ID yang bersumber dari file Transfer Data.Entitas enkripsi, yang merupakan kumpulan nilai unik yang digunakan untuk mengenkripsi ID pengguna. Nilai ini biasanya terkait dengan akun Campaign Manager 360 jika sumbernya adalah Transfer Data, atau pengiklan Campaign Manager 360 jika sumbernya adalah makro %m, tetapi tidak selalu demikian. Jika Anda tidak yakin, hubungi perwakilan akun Campaign Manager 360 Anda atau dukungan Campaign Manager 360 untuk informasi selengkapnya.
Jika diperlukan, membuat objek EncryptionInfo
yang menentukan nilai ini adalah langkah kedua dalam proses upload konversi:
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] )
Perhatikan bahwa setiap permintaan penyisipan hanya boleh berisi satu objek EncryptionInfo
. Artinya, semua konversi yang disertakan dalam permintaan tertentu harus
berasal dari sumber yang sama dan menggunakan entitas enkripsi yang sama.
Membuat permintaan penyisipan
Langkah terakhir dalam proses ini adalah mengupload konversi dengan panggilan ke
batchinsert
. Metode ini menerima objek ConversionsBatchInsertRequest
, yang menggabungkan kumpulan konversi yang akan diupload dengan info enkripsi terkait (jika diperlukan):
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=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)
Perhatikan bahwa Campaign Manager 360 mencoba menyisipkan setiap konversi dalam permintaan Anda berdasarkan upaya terbaik, bukan menyisipkan seluruh batch sebagai transaksi tunggal atau tidak sama sekali. Jika beberapa konversi dalam batch gagal disisipkan,
lainnya mungkin masih berhasil disisipkan. Oleh karena itu, sebaiknya
Anda memeriksa
ConversionsBatchInsertResponse
yang ditampilkan, untuk
menentukan status setiap konversi:
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
Kolom status
dari respons, seperti yang terlihat di atas, akan berisi objek ConversionStatus
untuk setiap konversi yang disertakan dalam permintaan asli. Jika Anda hanya tertarik pada konversi yang
gagal disisipkan, kolom hasFailures
dapat digunakan dengan cepat untuk menentukan apakah
salah satu konversi dalam batch yang diberikan gagal.
Memverifikasi bahwa konversi telah diproses
Konversi yang diupload biasanya akan diproses dan tersedia untuk dilaporkan dalam waktu 24 jam. Untuk memverifikasi apakah konversi yang telah Anda upload diproses atau tidak, sebaiknya jalankan laporan Tayangan Floodlight. Tidak seperti laporan atribusi lainnya, konversi ini akan menampilkan konversi yang diatribusikan (dikaitkan dengan iklan) dan yang tidak diatribusikan secara default. Oleh karena itu, sebaiknya periksa dengan cepat apakah konversi yang Anda kirim telah diterima Campaign Manager 360 atau tidak.