Insider API

​

Genel Bakış

Bu rehber, Hardal Analytics’i Hardal’ın Custom API bağlantılarını kullanarak Insider’ın API’si ile nasıl entegre edeceğinizi açıklar. Bu entegrasyonu kurarak, Hardal aracılığıyla toplanan kullanıcı event’lerini, özelliklerini ve diğer analitik verileri otomatik olarak doğrudan Insider’ın Unified Customer Database (UCD) sistemine gönderebilirsiniz.

​

Ön Koşullar

Entegrasyonu kurmadan önce, şunlara sahip olduğunuzdan emin olun:

• Website veya uygulamanızda tracking uygulanmış bir Hardal hesabı

• Hardal’ın Marketing Destinations bölümüne erişim

• API erişimi olan bir Insider hesabı

• Insider’dan API kimlik bilgileri:

  • Partner Name (kullanıcı adınızın yanındaki açılır menüde görünür)

  • Insider’ın Integration Settings’den Request Token (API anahtarı)

​

Hardal’da Custom API Bağlantısı Kurma

{
  "headers": {
    "X-PARTNER-NAME": "your_partner_name",
    "X-REQUEST-TOKEN": "your_api_token"
  }
}

{
  "users": [
    {
      "identifiers": {
        "email": "##user.email##",
        "uuid": "##user_id##",
        "custom": {
          "hardal_id": "##user_id##"
        }
      },
      "attributes": {
        "email_optin": ##user.email_optin##,
        "name": "##user.name##",
        "surname": "##user.surname##",
        "gender": "##user.gender##",
        "country": "##user.country##",
        "city": "##user.city##",
        "language": "##user.language##",
        "custom": {
          "source": "hardal_analytics"
        }
      },
      "events": [
        {
          "event_name": "##event_name##",
          "timestamp": "##created_at##",
          "event_params": ##properties##
        }
      ]
    }
  ]
}

​

Insider için Özel Event Yapılandırması

Insider’ın API’si, farklı event tipleri için belirli formatlama gerektirir. Yaygın event’ler için örnekler aşağıdadır:

​

Satın Alma Event’i

Satın alma event’leri için, event_group_id ve unit_sale_price gibi ek parametreler eklemeniz gerekir:

{
  "users": [
    {
      "identifiers": {
        "email": "##user.email##",
        "uuid": "##user_id##"
      },
      "events": [
        {
          "event_name": "purchase",
          "timestamp": "##created_at##",
          "event_params": {
            "product_id": "##properties.product_id##",
            "name": "##properties.product_name##",
            "unit_price": ##properties.price##,
            "unit_sale_price": ##properties.sale_price##,
            "event_group_id": "##properties.order_id##",
            "taxonomy": ##properties.categories##,
            "currency": "##properties.currency##",
            "quantity": ##properties.quantity##
          }
        }
      ]
    }
  ]
}

​

Kullanıcı Kayıt Event’i

Kullanıcı kayıt event’leri için:

{
  "users": [
    {
      "identifiers": {
        "email": "##user.email##",
        "uuid": "##user_id##"
      },
      "attributes": {
        "email_optin": true,
        "name": "##user.name##",
        "surname": "##user.surname##"
      },
      "events": [
        {
          "event_name": "account_created",
          "timestamp": "##created_at##",
          "event_params": {
            "custom": {
              "registration_source": "##properties.source##",
              "registration_method": "##properties.method##"
            }
          }
        }
      ]
    }
  ]
}

​

Yaygın Insider API Gereksinimlerini Yönetme

​

Satın Alma Event’leri için Gerekli Parametreler

Insider’a satın alma event’leri gönderirken, şu parametrelerin dahil edildiğinden emin olun:

• event_group_id: Satın alma event’leri için gereklidir (genellikle bir sipariş ID’si)

• unit_sale_price: Satın alma event’leri için gereklidir (indirimlerden sonraki fiyat)

• currency: Satın alma event’leri için gereklidir (ISO 4217 formatında, örn. “USD”)

​

Zaman Damgalarını Formatlama

Insider, RFC 3339 formatında zaman damgaları gerektirir. Hardal’ın ##created_at## değişkeni bu formatta çıktı verir, ancak tarihleri manipüle ediyorsanız, şu deseni izlediğinden emin olun: YYYY-MM-DDThh:mm:ssZ veya saat dilimi ofseti ile YYYY-MM-DDThh:mm:ss±hh:mm.

​

Dizi Özelliklerini Yönetme

Varsayılan olarak, bir kullanıcı için dizi özellikleri gönderirken, Insider yeni değerleri mevcut olanlara ekler. Dizi özelliklerini eklemek yerine değiştirmek istiyorsanız, isteğinize "not_append": true ekleyin:

{
  "users": [
    {
      "identifiers": { ... },
      "attributes": { ... },
      "not_append": true,
      "events": [ ... ]
    }
  ]
}

​

Sorun Giderme

​

Örnek: Tam Custom Bağlantı Yapılandırması

İşte hem kullanıcı özelliklerini hem de satın alma event’lerini Insider’a göndermek için tam bir Custom API yapılandırma örneği:

​

Başlık Yapılandırması

{
  "headers": {
    "X-PARTNER-NAME": "mybrand",
    "X-REQUEST-TOKEN": "1a2b3c4e5d6f",
    "Content-Type": "application/json"
  }
}

​

İstek Gövdesi Yapılandırması

{
  "skip_hook": false,
  "users": [
    {
      "identifiers": {
        "email": "##user.email##",
        "uuid": "##user_id##",
        "custom": {
          "user_loyalty_id": "##user.loyalty_id##"
        }
      },
      "attributes": {
        "email_optin": "##user.email_optin##",
        "age": "##user.age##",
        "language": "##user.language##",
        "birthday": "##user.birthday##",
        "custom": {
          "source": "hardal_analytics",
          "favorite_color": "##user.favorite_color##"
        }
      },
      "events": [
        {
          "event_name": "##event_name##",
          "timestamp": "##created_at##",
          "event_params": {
            "product_id": "##properties.product_id##",
            "name": "##properties.product_name##",
            "unit_price": "##properties.price##",
            "unit_sale_price": "##properties.sale_price##",
            "event_group_id": "##properties.order_id##",
            "taxonomy": ["##properties.category##"],
            "currency": "##properties.currency##",
            "quantity": "##properties.quantity##",
            "custom": {
              "source_page": "##page.url##",
              "device_type": "##device_type##"
            }
          }
        }
      ]
    }
  ]
}

​

En İyi Uygulamalar

1. Kritik event’lerle başlayın: Diğer event tiplerine genişlemeden önce satın alma ve kayıt gibi yüksek değerli event’leri göndermeye başlayın.

2. Veri kalitesini izleyin: Verilerin doğru aktığından emin olmak için hem Hardal hem de Insider dashboard’larını düzenli olarak kontrol edin.

3. Geçmiş veriler için skip_hook kullanın: Geçmiş verileri gönderirken, mevcut journey’leri tetiklememek için skip_hook: true ayarlayın.

4. Kullanıcıları verimli şekilde gruplandırın: Her istek 1.000’e kadar kullanıcı içerebilir, ancak istek boyutunu 5MB’ın altında tutun.

5. Hataları uygun şekilde yönetin: Başarısız istekler için uygun hata günlüğü ve yeniden deneme mekanizmaları uygulayın.

6. Kapsamlı test yapın: Tam olarak uygulamadan önce her zaman çeşitli event tipleriyle bağlantınızı test edin.

7. Veri tutarlılığını koruyun: Tanımlayıcıların ve event parametrelerinin platformlar arasında tutarlı olduğundan emin olun.

​

İlgili Kaynaklar

• Hardal Custom API Dokümantasyonu

• Insider Upsert API Dokümantasyonu

• Hardal Event Tracking Rehberi