Dönüşümleri yükle

Bu kılavuzda, Campaign Manager 360 API Conversions hizmetini kullanarak çevrimdışı dönüşümleri yükleme hakkında ayrıntılı talimatlar verilmektedir. Devam etmeden önce, çevrimdışı dönüşümlere giriş yapmak ve bu kılavuzda ele alınan kavramlar hakkında bilgi edinmek için Genel Bakış bölümünü incelemeniz önerilir.

Not: API, Campaign Manager 360 ve Display & Video 360 için çevrimdışı dönüşümleri desteklese de alışveriş sepeti verileri bu ürünlerin ikisinde de kullanılamaz. Alışveriş sepeti verileri hakkında daha fazla bilgi edinin.

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

Dönüşüm yükleme sürecinin 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ı cihazdan veya aynı kullanıcıdan aynı gün içinde gelen dönüşümlerin nasıl tekilleştirileceğini kontrol etmek için kullanılan değer. Daha fazla bilgi için SSS bölümüne bakın.
timestampMicros	Dönüşümün zaman damgası (Unix sıfır zamanından itibaren mikrosaniye cinsinden).

Ayrıca, her nesne aşağıdaki alanlardan birini içermelidir:

Alan	Açıklama
encryptedUserId	%m eşleşme makrosundan veya Veri Aktarımı'ndan elde edilen tek bir şifrelenmiş kullanıcı kimliği.
encryptedUserIdCandidates[]	%m eşleşme makrosundan veya Veri Aktarımı'ndan elde edilen şifrelenmiş kullanıcı kimliklerinin listesi. Belirtilen timestampMicros tarihinden önce Floodlight gösterimi kaydedilmiş olan bu kimliklerden ilki kullanılır. Kimliklerden hiçbiri mevcut bir gösterimle eşleşmezse hata verilir.
dclid	Campaign Manager 360 veya Display & Video 360 tarafından oluşturulan bir Görüntülü Reklam Ağı tıklama kimliği.
gclid	Google Ads veya Search Ads 360 tarafından oluşturulan bir Google tıklama kimliği.
matchId	Reklamveren tarafından oluşturulan ve Floodlight etiketi aracılığıyla Campaign Manager 360'a iletilen benzersiz bir tanımlayıcı.
mobileDeviceId	IDFA veya AdID biçimindeki şifrelenmemiş bir mobil kimlik ya da desteklenen bir bağlı TV cihazı platformundan (Roku, Fire TV, Android TV, Apple TV, Xbox, Samsung, Vizio) reklam amaçlı bağlı TV tanımlayıcısı (IFA). Google'ın YouTube bağlı TV IFA'larını desteklemediğini unutmayın.

Son olarak, her dönüşümün iki metriği vardır:

Alan	Açıklama
quantity	Zorunlu. Dönüşümle ilişkilendirilmiş öğe sayısı. Dönüşümün belirli metriklerde (ör. toplam dönüşüm) sayılması için en az 1 olmalıdır.
value	Dönüşümle ilişkili ABD doları tutarı. Dönüşümün değeri, Floodlight yapılandırmasına sahip reklamverenin para birimine göre yorumlanır.

İsteğe bağlı alanlar referans belgelerinde açıklanmıştır.

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

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=str(profile_id), id=str(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 belirtme

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

Önceki örnekte olduğu gibi, çevrimdışı dönüşümleri şifrelenmiş kullanıcı kimlikleriyle ilişkilendirmeyi planlıyorsanız ekleme isteğinizin bir parçası olarak, bunların nasıl şifrelendiğiyle ilgili bazı ayrıntılar sağlamanız gerekir. Özellikle bilmeniz gerekenler:

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

2. Kullanıcı kimliklerini şifrelemek için kullanılan benzersiz bir değer grubu olan şifreleme öğesi. Bu değerler normalde kaynak Veri Aktarımı olduğunda bir Campaign Manager 360 hesabı, kaynak %m makrosu olduğunda ise bir Campaign Manager 360 reklamvereniyle ilgilidir ancak bu her zaman geçerli değildir. Emin değilseniz daha fazla bilgi için Campaign Manager 360 hesap temsilcinizle veya Campaign Manager 360 Destek Ekibi ile iletişime geçin.

Gerekli olduğunda, bu değerleri belirten bir EncryptionInfo nesnesi oluşturmak, dönüşüm yükleme sürecindeki ikinci adımdı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);

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

Her ekleme isteğinin yalnızca bir EncryptionInfo nesnesi içerebileceğini unutmayın. Bu, belirli bir isteğe dahil edilen tüm dönüşümlerin aynı kaynaktan gelmesi ve aynı şifreleme kuruluşunu kullanması gerektiği anlamına gelir.

Ekleme isteği oluşturma

Bu sürecin son adımı, dönüşümlerinizi batchinsert çağrısıyla yüklemektir. Bu yöntem, yüklenecek dönüşüm grubunu ilişkili şifreleme bilgileriyle (gerekli olduğunda) birleştiren bir ConversionsBatchInsertRequest nesnesini kabul eder:

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=str(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 grubu her şey dahil bir işlem olarak eklemek yerine isteğinizdeki her dönüşümü en iyi çaba temelinde eklemeye çalıştığını unutmayın. Bir toplu işlemdeki bazı dönüşümler eklenemezse diğerleri yine de başarıyla eklenebilir. Bu nedenle, her dönüşümün durumunu belirlemek için döndürülen ConversionsBatchInsertResponse öğesini 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());
  }
}

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

Yukarıda görüldüğü gibi, yanıttaki status alanı, orijinal isteğe dahil edilen her dönüşüm için bir ConversionStatus nesnesi içerir. Yalnızca eklenemeyen dönüşümlerle ilgileniyorsanız hasFailures alanı, sağlanan toplu işlemdeki herhangi bir dönüşümün başarısız olup olmadığını hızlı bir şekilde 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 raporlanabilir hale gelir. Yüklediğiniz dönüşümlerin işlenip işlenmediğini doğrulamak için Floodlight gösterim raporu çalıştırmanız önerilir. Diğer ilişkilendirme raporlarının aksine, bu raporlar varsayılan olarak hem ilişkilendirilmiş (bir reklamla ilişkili) 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 yapılmalıdır. Floodlight gösterimleri raporları, zaman damgalarından 28 gün sonra gönderilen dönüşümleri yansıtmaz.