Etkinlikleri gönder

Etkinlik verilerini gönderme hakkında bilgi edinmek için bu hızlı başlangıç kılavuzunu inceleyebilirsiniz.

Aşağıdaki senaryolardan birinde Veri Yöneticisi API'sini kullanın:

• Online etkinlikler: Reklam etkileşimi sinyallerini en üst düzeye çıkarmak, verilerinizi ve genel performansı güçlendirmek için etkinlik verilerini etiket dönüşümleriniz için ek bir veri kaynağı olarak gönderin.

• Çevrimdışı etkinlikler: Çevrimdışı dönüşümler veya potansiyel müşteriler için gelişmiş dönüşümler ile ilgili etkinlik verilerini gönderin.

Görmek istediğiniz kılavuz sürümünü seçin:

Reklamveren Veri İş Ortağı

Bu hızlı başlangıç kılavuzunda aşağıdaki adımları tamamlayacaksınız:

1. Etkinlik verilerini almak için bir Destination hazırlayın.
2. Gönderilecek etkinlik verilerini hazırlayın.
3. Etkinlikler için IngestionService isteği oluşturun.
4. İsteği Google API Gezgini ile gönderin.
5. Başarı ve hata yanıtlarını anlama

Hedef hazırlama

Veri gönderebilmek için verilerin gönderileceği hedefi hazırlamanız gerekir. Kullanabileceğiniz örnek bir Destination aşağıda verilmiştir:

    {
      "operatingAccount": {
        "product": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "CONVERSION_ACTION_1_ID"
    }

• accountId öğesini, etkinlik verilerini alacak Google Ads hesap kimliğine ayarlayın.operatingAccount operatingAccount öğesinin product değeri GOOGLE_ADS olmalıdır.

• Etkinlikler için productDestinationId değerini dönüşüm işleminin kimliği olarak ayarlayın. Online etkinlikler için dönüşüm işlemi, type değeri WEBPAGE olarak ayarlanmış bir Google Ads dönüşüm işlemi olmalıdır. Çevrimdışı etkinlikler için dönüşüm işlemi, type değeri UPLOAD_CLICKS olarak ayarlanmış bir Google Ads dönüşüm işlemi olmalıdır.

  Bu kılavuzda, her etkinliği aynı dönüşüm işlemine gönderen bir isteğin nasıl oluşturulacağı gösterilmektedir. Aynı istekte birden fazla dönüşüm işlemi için etkinlik göndermek istiyorsanız birden fazla hedef bölümüne bakın.

Etkinlik verilerini hazırlama

Aşağıdaki etkinlik verilerini göz önünde bulundurun. Her tablo bir dönüşüm etkinliğine karşılık gelir. Her dönüşüm etkinliğinde etkinliğin zaman damgası, dönüşüm işlemi ve dönüşüm değeri bulunur.

Her etkinlikte gclid gibi reklam tanımlayıcıları veya e-posta adresleri, telefon numaraları ve adres bilgileri gibi kullanıcı tanımlayıcıları olabilir. Bir etkinlikte, etkinlik sırasında değerlendirilen kullanıcıyla ilgili bilgiler de bulunabilir. Örneğin, müşterinin değeri veya yeni, geri gelen ya da yeniden etkileşime giren bir müşteri olup olmadığı.

İlk etkinliğin verileri:

İkinci etkinliğin verileri:

Verileri biçimlendirme

Alanları, biçimlendirme kılavuzunda belirtildiği şekilde biçimlendirin. Biçimlendirmeden sonraki ilk etkinliğin verileri aşağıda verilmiştir:

İkinci etkinliğin biçimlendirilmiş verileri aşağıda verilmiştir:

Verileri anonimleştirme ve kodlama

Ayrıca, biçimlendirilmiş e-posta adresleri, adlar ve soyadlar SHA-256 algoritması kullanılarak karma oluşturma işlemine tabi tutulmalı ve onaltılık veya Base64 kodlaması kullanılarak kodlanmalıdır. Biçimlendirme, karma oluşturma ve kodlama işlemlerinden sonra onaltılık kodlama kullanılarak oluşturulan ilk etkinliğin verileri aşağıda verilmiştir:

İkinci etkinliğin verileri, onaltılık kodlama kullanılarak biçimlendirildikten, karma oluşturulduktan ve kodlandıktan sonra aşağıdaki gibi görünür:

Verileri Event biçimine dönüştürme

Her etkinliğin biçimlendirilmiş ve karma oluşturma işlemi uygulanmış verilerini Event olarak dönüştürün. Aşağıdaki zorunlu alanları doldurun:

• event_timestamp: Etkinliğin gerçekleştiği zaman.
• transaction_id: Etkinliğin benzersiz tanımlayıcısı.
• event_source: Etkinliğin kaynağı. Çevrimdışı etkinlikler için gereklidir. Online etkinlikler için isteğe bağlıdır. Çevrimiçi etkinlik için belirtilmişse WEB olmalıdır.
• ad_identifiers veya user_data: Etkinlikte bir reklam tanımlayıcı ya da kullanıcı verileri olmalıdır. Etkinlik için her ikisi de varsa her ikisini de gönderin.

Kullanılabilir alanların tam listesi için Event referans belgelerine bakın. Etkinlik için değerinizin olduğu tüm alanları doldurun.

İkinci etkinlikten alınan biçimlendirilmiş, karma oluşturma işlemi uygulanmış ve kodlanmış veriler için örnek bir Event aşağıda verilmiştir:

{
   "adIdentifiers": {
      "gclid": "GCLID_2"
   },
   "conversionValue": 3.25,
   "currency": "EUR",
   "eventTimestamp": "2025-06-10T23:42:33-05:00",
   "transactionId": "DEF999911111",
   "eventSource": "WEB",
   "userData": {
      "userIdentifiers": [
         {
            "emailAddress": "3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250"
         },
         {
            "emailAddress": "223EBDA6F6889B1494551BA902D9D381DAF2F642BAE055888E96343D53E9F9C4"
         },
         {
            "address": {
              "givenName": "2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450",
              "familyName": "6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F",
              "regionCode": "PT",
              "postalCode": "1229-076"
            }
         }
      ],
      "userProperties": {
        "customerType": "RETURNING"
      }
   }
}

İstek gövdesini oluşturma

İstek gövdesi için Destination ve Events değerlerini birleştirin:

{
  "destinations": [
    {
      "operatingAccount": {
        "product": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "CONVERSION_ACTION_1_ID"
    }
  ],
  "encoding": "HEX",
  "events": [
     {
       "adIdentifiers": {
         "gclid": "GCLID_1"
       },
       "conversionValue": 1.99,
       "currency": "USD",
       "eventTimestamp": "2025-06-10T20:07:01Z",
       "transactionId": "ABC798654321",
       "eventSource": "WEB",
       "userData": {
         "userIdentifiers": [
           {
             "address": {
               "givenName": "96D9632F363564CC3032521409CF22A852F2032EEC099ED5967C0D000CEC607A",
               "familyName": "DB98D2607EFFFA28AFF66975868BF54C075ECA7157E35064DCE08E20B85B1081",
               "regionCode": "US",
               "postalCode": "94045"
             }
           }
         ]
       },
       "userProperties": {
         "customerType": "NEW",
         "customerValueBucket": "HIGH"
       }
     },
     {
       "adIdentifiers": {
         "gclid": "GCLID_2"
       },
       "conversionValue": 3.25,
       "currency": "EUR",
       "eventTimestamp": "2025-06-11T04:42:33Z",
       "transactionId": "DEF999911111",
       "eventSource": "WEB",
       "userData": {
         "userIdentifiers": [
           {
             "emailAddress": "3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250"
           },
           {
             "emailAddress": "223EBDA6F6889B1494551BA902D9D381DAF2F642BAE055888E96343D53E9F9C4"
           },
           {
             "address": {
               "givenName": "2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450",
               "familyName": "6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F",
               "regionCode": "PT",
               "postalCode": "1229-076"
             }
           }
         ]
       },
       "userProperties": {
         "customerType": "RETURNING"
       }
     }
  ],
  "validateOnly": true
}

1. Gövdedeki yer tutucuları (ör. OPERATING_ACCOUNT_ID ve CONVERSION_ACTION_1_ID) hesabınızın ve hedefinizin değerleriyle güncelleyin.
2. Değişiklikleri uygulamadan isteği doğrulamak için validateOnly değerini true olarak ayarlayın. Değişiklikleri uygulamaya hazır olduğunuzda validateOnly seçeneğini false olarak ayarlayın.
3. Bu örnekte şifreleme kullanılmadığını unutmayın.

İsteği gönderin

1. Örneğin sağ üst kısmındaki kopyalama düğmesini kullanarak istek gövdesini kopyalayın.
2. Araç çubuğunda API düğmesini tıklayın.
3. Kopyalanan istek gövdesini İstek gövdesi kutusuna yapıştırın.
4. Execute (Yürüt) düğmesini tıklayın, yetkilendirme istemlerini tamamlayın ve yanıtı inceleyin.

Başarılı yanıtlar

Başarılı bir istek, requestId içeren bir nesneyle yanıt döndürür.

{
  "requestId": "126365e1-16d0-4c81-9de9-f362711e250a"
}

Hata yanıtları

Başarısız bir istek, 400 Bad Request gibi bir hata yanıtı durum kodu ve hata ayrıntılarını içeren bir yanıtla sonuçlanır.

Örneğin, onaltılık kodlanmış değer yerine düz metin dizesi içeren bir email_address aşağıdaki yanıtı üretir:

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "events.events[0].user_data.user_identifiers",
            "description": "Email is not hex encoded.",
            "reason": "INVALID_HEX_ENCODING"
          }
        ]
      }
    ]
  }
}

Karma oluşturulmamış ve yalnızca on altılık olarak kodlanmış bir email_address aşağıdaki yanıtı üretir:

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "events.events[0]",
            "reason": "INVALID_SHA256_FORMAT"
          }
        ]
      }
    ]
  }
}

Birden fazla hedef için etkinlik gönderme

Verileriniz farklı hedeflere yönelik etkinlikler içeriyorsa hedef referanslarını kullanarak bunları aynı istekte gönderebilirsiniz.

Örneğin, 123456789 dönüşüm işlemi kimliği için bir etkinliğiniz ve 777111122 dönüşüm işlemi kimliği için başka bir etkinliğiniz varsa her Destination öğesinin reference değerini ayarlayarak her iki etkinliği de tek bir istekte gönderin. reference, kullanıcı tarafından tanımlanır. Tek koşul, her Destination öğesinin benzersiz bir reference değerine sahip olmasıdır. İstek için değiştirilmiş destinations listesi:

  "destinations": [
    {
      "operatingAccount": {
        "product": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "123456789"
      "reference": "conversion_action_1"
    },
    {
      "operatingAccount": {
        "product": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "777111122"
      "reference": "conversion_action_2"
    }
  ]

Her Event öğesinin destination_references değerini, bir veya daha fazla belirli hedefe gönderecek şekilde ayarlayın. Örneğin, burada yalnızca ilk Event için olan bir Destination var. Bu nedenle, destination_references listesinde yalnızca ilk Destination'nin reference yer alıyor:

{
   "adIdentifiers": {
      "gclid": "GCLID_1"
   },
   "conversionValue": 1.99,
   "currency": "USD",
   "eventTimestamp": "2025-06-10T20:07:01Z",
   "transactionId": "ABC798654321",
   "eventSource": "WEB",
   "destinationReferences": [
      "conversion_action_1"
   ]
}

destination_references alanı bir liste olduğundan bir etkinlik için birden fazla hedef belirtebilirsiniz. Bir destination_references öğesinin Event değerini ayarlamazsanız Veri Yöneticisi API'si, etkinliği istekteki tüm hedeflere gönderir.

Sonraki adımlar

• Kimlik doğrulama yapılandırın ve ortamınızı bir istemci kitaplığıyla ayarlayın.
• Her veri türü için biçimlendirme, karma oluşturma ve kodlama koşulları hakkında bilgi edinin.
• Kullanıcı verilerini nasıl şifreleyeceğinizi öğrenin.
• En iyi uygulamalar hakkında bilgi edinin.
• Sınırlar ve kotalar hakkında bilgi edinin.