Upload konversi

Panduan ini memberikan petunjuk mendetail untuk mengupload konversi offline menggunakan layanan Conversions Campaign Manager 360 API. Sebelum melanjutkan, sebaiknya Anda meninjau Ringkasan untuk mendapatkan pengantar tentang konversi offline dan memahami konsep yang dibahas dalam panduan ini.

Catatan: Meskipun API mendukung konversi offline untuk Campaign Manager 360 dan Display & Video 360, Data Keranjang tidak tersedia untuk salah satu produk tersebut. Pelajari Data Keranjang lebih lanjut.

Mengonfigurasi 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:

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 penghapusan duplikat konversi dari perangkat atau pengguna yang sama pada hari yang sama. Lihat FAQ untuk mengetahui informasi selengkapnya.
timestampMicros	Stempel waktu konversi, dalam mikrodetik sejak epoch Unix.

Selain itu, setiap objek harus berisi 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%m atau Transfer Data. ID pertama dari ID ini dengan eksposur Floodlight yang dicatat 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 dan diteruskan ke Campaign Manager 360 melalui tag Floodlight.
mobileDeviceId	ID seluler yang tidak dienkripsi dalam format IDFA atau AdID 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 TV yang Terhubung YouTube.

Kolom opsional didokumentasikan dalam dokumentasi referensi. Perhatikan bahwa kolom jumlah, meskipun bersifat opsional, harus minimal 1 agar konversi dihitung dalam metrik tertentu (seperti Total Konversi) saat menjalankan laporan.

Contoh di bawah ini mengilustrasikan 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

Catatan: Bagian ini hanya berlaku saat mengupload konversi yang berisi encryptedUserId atau encryptedUserIdCandidates[].

Jika Anda berencana mengatribusikan konversi offline ke ID pengguna terenkripsi, seperti dalam contoh sebelumnya, Anda harus memberikan beberapa detail tentang cara ID tersebut dienkripsi sebagai bagian dari permintaan penyisipan Anda. Secara khusus, Anda perlu mengetahui:

1. Sumber enkripsi, yang menjelaskan asal batch ID terenkripsi. Nilai yang dapat diterima adalah AD_SERVING untuk ID yang berasal dari makro pencocokan %m, atau DATA_TRANSFER untuk ID yang berasal dari file Transfer Data.

2. 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 atau dukungan Campaign Manager 360 untuk mendapatkan informasi selengkapnya.

Jika perlu, 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 semua atau tidak sama sekali. Jika beberapa konversi dalam batch gagal disisipkan, konversi 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 respons, seperti yang terlihat di atas, akan berisi objek ConversionStatus untuk setiap konversi yang disertakan dalam permintaan asli. Jika Anda hanya tertarik dengan konversi yang gagal dimasukkan, kolom hasFailures dapat digunakan untuk menentukan dengan cepat apakah ada konversi apa pun dalam batch yang diberikan yang 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 Anda upload telah diproses atau tidak, sebaiknya jalankan laporan Tayangan Floodlight. Tidak seperti laporan atribusi lainnya, laporan ini akan menampilkan konversi yang diatribusikan (dikaitkan dengan iklan) dan konversi yang tidak diatribusikan secara default. Hal ini membuatnya ideal untuk memeriksa dengan cepat apakah konversi yang Anda kirim telah sampai ke Campaign Manager 360.

Catatan: Pengujian verifikasi harus dilakukan menggunakan konversi terbaru. Laporan Tayangan Floodlight tidak akan mencerminkan konversi yang dikirimkan lebih dari 28 hari setelah stempel waktunya.