Dönüşümleri yükle

Bu kılavuzda, Campaign Manager 360 API'si Conversions hizmetini kullanarak çevrimdışı dönüşümleri yüklemeyle ilgili ayrıntılı talimatlar verilmektedir. Devam etmeden önce, çevrimdışı dönüşümlere giriş yapmak ve bu kılavuzda açıklanan kavramları öğrenmek için Genel Bakış sayfasını incelemeniz önerilir.

Dönüşüm kaynaklarını yapılandırın

Dönüşüm yükleme işleminin ilk adımı, bir veya daha fazla Conversion kaynak nesnesi oluşturmaktır. Bu nesnelerin her biri tek bir dönüşüm etkinliğini temsil eder ve birkaç zorunlu alanı içerir:

Alan	Açıklama
floodlightActivityId	Bu dönüşümün ilişkilendirileceği Floodlight etkinliği.
floodlightConfigurationId	Belirtilen etkinlik tarafından kullanılan Floodlight yapılandırması.
ordinal	Aynı gün veya cihazdan aynı cihazdan elde edilen dönüşümlerin tekilleştirilmesini kontrol etmek için kullanılan değer. Daha fazla bilgi için SSS bölümüne bakın.
timestampMicros	Unix döneminden bu yana geçen, mikrosaniye cinsinden dönüşümün zaman damgası.

Buna ek olarak her nesne, aşağıdaki alanlardan birini içermelidir:

Alan	Açıklama
encryptedUserId	%m eşleşme makrosu veya Veri Aktarımı'ndan alınan tek bir şifrelenmiş kullanıcı kimliği.
encryptedUserIdCandidates[]	%m eşleşme makrosu veya Veri Aktarımı'ndan elde edilen şifrelenmiş kullanıcı kimliklerinin listesi. Belirtilen timestampMicros öncesinde bir Floodlight gösterimine sahip olan bu kimliklerin ilki kullanılacak. Kimliklerden hiçbiri mevcut bir karşılaşmayla eşleşmezse hata verilir.
dclid	Campaign Manager 360 veya Display & Video 360 tarafından oluşturulan bir Görüntülü Reklam Tıklama Tanımlayıcısı.
gclid	Google Ads veya Search Ads 360 tarafından oluşturulan bir Google Tıklama Kimliği.
matchId	Bir Floodlight etiketi aracılığıyla Campaign Manager 360'a iletilen reklamveren tarafından oluşturulan benzersiz tanımlayıcı.
mobileDeviceId	Desteklenen bir CTV cihaz platformundan (Roku, Fire TV, Android TV, Apple TV, Xbox, Samsung, Vizio) IDFA veya Reklam Kimliği biçiminde şifrelenmemiş mobil kimlik ya da Reklam İçin Bağlı TV Tanımlayıcısı (IFA). Google'ın, YouTube Bağlı TV IFA'larını desteklemediğini unutmayın.

İsteğe bağlı alanlar referans dokümanlarda açıklanmıştır. İsteğe bağlı olarak miktar alanı, raporları çalıştırırken dönüşümün belirli metriklere (Toplam Dönüşümler gibi) dahil edilmesi için en az 1 olması gerektiğini unutmayın.

Aşağıdaki örnekte basit bir dönüşüm kaynağı nesnesinin oluşturulması gösterilmektedir:

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

2.999

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

Şifreleme bilgilerini belirtin

Not: Bu bölüm yalnızca encryptedUserId veya encryptedUserIdCandidates[] içeren dönüşümleri yüklerken geçerlidir.

Önceki örnekte olduğu gibi, çevrimdışı dönüşümleri şifrelenmiş kullanıcı kimlikleriyle ilişkilendirmeyi planlıyorsanız, ekleme isteğiniz kapsamında bunların nasıl şifrelendiğiyle ilgili bazı ayrıntıları paylaşmanız gerekir. Özellikle şu bilgileri bilmeniz gerekir:

1. Şifrelenmiş bir kimlik grubunun nereden geldiğini açıklayan şifreleme kaynağı. Kabul edilebilir değerler, %m eşleşme makrosundan elde edilen kimlikler için AD_SERVING veya Veri Aktarımı dosyalarından alınan kimlikler için DATA_TRANSFER'dir.

2. Kullanıcı kimliklerini şifrelemek için kullanılan benzersiz bir değer kümesi olan şifreleme varlığı. Bu değerler normalde, kaynak Veri Aktarımı olduğunda bir Campaign Manager 360 hesabıyla, kaynak %m makrosu olduğunda ise bir Campaign Manager 360 reklamvereniyle ilişkilidir. Ancak bu durum her zaman geçerli olmayabilir. Emin değilseniz daha fazla bilgi için Campaign Manager 360 hesap temsilcinizle veya Campaign Manager 360 destek ekibiyle iletişime geçin.

Gerektiğinde dönüşüm yükleme işleminin ikinci adımı bu değerleri belirten bir EncryptionInfo nesnesi oluşturmaktır:

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

2.999

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

Her ekleme isteğinin yalnızca bir EncryptionInfo nesnesi içerebileceğini unutmayın. Yani, belirli bir istekte yer alan tüm dönüşümler aynı kaynaktan kaynaklanmalı ve aynı şifreleme varlığını kullanmalıdır.

Ekleme isteği oluştur

Bu süreçteki son adım, batchinsert çağrısıyla dönüşümlerinizi yüklemektir. Bu yöntem bir ConversionsBatchInsertRequest nesnesini kabul eder. Bu nesne, yüklenecek şifreleme grubunu, ilişkili şifreleme bilgileriyle (gerekirse) birleştirir.

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

2.999

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

Campaign Manager 360'ın, tüm dönüşümü bir "ya hep ya hiç" işlemi olarak eklemek yerine, her bir isteği talebinize en iyi çaba esasına göre eklemeye çalıştığınızı unutmayın. Bir gruptaki bazı dönüşümler eklenemezse diğer dönüşümler de başarıyla eklenebilir. Bu nedenle, her bir dönüşümün durumunu belirlemek için döndürülen ConversionsBatchInsertResponse dosyasını incelemeniz önerilir:

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

2.999

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

Yukarıda görüldüğü gibi, yanıtın status alanı, orijinal isteğe dahil edilen her dönüşüm için bir ConversionStatus nesnesi içerir. Yalnızca eklenemeyen dönüşümler ilginizi çekiyorsa hasFailures alanı, sağlanan gruptaki herhangi bir dönüşümün başarısız olup olmadığını hızlıca belirlemek için kullanılabilir.

Dönüşümlerin işlendiğini doğrulama

Yüklenen dönüşümler genellikle 24 saat içinde işlenir ve raporlanmaya hazır olur. Yüklediğiniz dönüşümlerin işlenip işlenmediğini doğrulamak için bir Floodlight Gösterimleri raporu çalıştırmanız önerilir. Diğer ilişkilendirme raporlarının aksine, bunlar varsayılan olarak hem ilişkilendirilen (bir reklamla ilişkilendirilmiş) hem de ilişkilendirilmemiş dönüşümleri döndürür. Bu sayede, gönderdiğiniz dönüşümlerin Campaign Manager 360'a ulaşıp ulaşmadığını hızlıca kontrol edebilirsiniz.

Not: Doğrulama testi, son dönüşümler kullanılarak gerçekleştirilmelidir. Floodlight Gösterimleri raporları, zaman damgalarından 28 günden uzun bir süre sonra gönderilen dönüşümleri yansıtmaz.