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

  1. Sumber enkripsi, yang menjelaskan asal batch ID terenkripsi. Nilai yang dapat diterima adalah AD_SERVING untuk ID yang bersumber dari makro pencocokan %m, atau DATA_TRANSFER untuk ID yang bersumber 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 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.