Dönüşümleri yükle

Bu kılavuzda, Campaign Manager 360 API Conversions hizmetini kullanarak çevrimdışı dönüşümleri yüklemeyle ilgili ayrıntılı talimatlar sağlanmaktadır. Devam etmeden önce, çevrimdışı dönüşümlere giriş yapmak ve bu kılavuzda ele alınan kavramlarla ilgili 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 hiçbirinde 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 kullanıcıdan aynı gün yapılan dönüşümlerin nasıl tekilleştirileceğini kontrol etmek için kullanılan bir değerdir. Daha fazla bilgi için SSS bölümünü inceleyin.
timestampMicros	Unix sıfır zamanından itibaren mikrosaniye cinsinden dönüşümün zaman damgası.

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

Alan	Açıklama
encryptedUserId	%m eşleme makrosundan veya Veri Aktarımı'ndan elde edilen tek bir şifrelenmiş kullanıcı kimliği.
encryptedUserIdCandidates[]	%m eşleştirme makrosundan veya Veri Aktarımı'ndan elde edilen şifrelenmiş kullanıcı kimliklerinin listesi. Belirtilen timestampMicros tarihinden önce kaydedilmiş Floodlight gösterimi olan bu kimliklerden ilki kullanılır. Kimliklerden hiçbiri mevcut bir gösterimle eşleşmezse hata meydana gelir.
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 Tanımlayıcısı.
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çiminde şifrelenmemiş bir mobil kimlik ya da desteklenen bir CTV cihaz platformundan (Roku, Fire TV, Android TV, Apple TV, Xbox, Samsung, Vizio) Reklam için Bağlı TV Tanımlayıcısı (IFA). Google, YouTube Bağlı TV IFA'larını desteklemez.

İsteğe bağlı alanlar referans dokümanlarında açıklanmıştır. Raporlar çalıştırıldığında dönüşümün belirli metrikler (ör. toplam dönüşüm sayısı) için sayılabilmesi amacıyla, isteğe bağlı olsa da miktar alanının en az 1 olması gerektiğini unutmayın.

Aşağıdaki örnekte basit bir dönüşüm kaynağı nesnesi 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=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üşümler yüklenirken geçerlidir.

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

1. Şifrelenmiş kimliklerden oluşan bir grubun nereden geldiğini açıklayan şifreleme kaynağı. Kabul edilen değerler, %m eşleme makrosundan alınan 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 grubu olan şifreleme öğesi. Bu değerler, kaynak Veri Aktarımı olduğunda normalde bir Campaign Manager 360 hesabıyla veya kaynak %m makrosu olduğunda bir Campaign Manager 360 reklamvereniyle ilgilidir ancak her zaman böyle 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.

Gerekirse dönüşüm yükleme sürecinin 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);

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 öğesini 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 (gerekirse) 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=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 ya hep ya hiç işlemi olarak eklemek yerine her dönüşümü isteğinize en iyi çabayla eklemeye çalıştığını unutmayın. Bir gruptaki bazı dönüşümler eklenemezse diğerleri 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ıtın status alanında, orijinal isteğe dahil edilen her dönüşüm için bir ConversionStatus nesnesi bulunur. Yalnızca eklenemeyen dönüşümlerle ilgileniyorsanız sağlanan gruptaki herhangi bir dönüşümün başarısız olup olmadığını hızlıca belirlemek için hasFailures alanını kullanabilirsiniz.

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 bir Floodlight Gösterimleri 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şkilendirilmiş) hem de ilişkilendirilmemiş dönüşümleri döndürür. Bu, gönderdiğiniz dönüşümlerin Campaign Manager 360'a ulaşıp ulaşmadığını hızlıca kontrol etmek için idealdir.

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