İçeriğe geç

API Referansı

Bu doküman, SegmentHub REST API'sini kullanarak ziyaretçilerinize ait meta verileri nasıl sorgulayıp yöneteceğinizi, olayları platforma nasıl ileteceğinizi ve segmentleri gerçek zamanlı olarak nasıl aktive edeceğinizi açıklar.

Açıklama

REST API'ye bir istek gönderdiğinizde bir HTTP metodu ve bir yol (path) belirtirsiniz. Bunlara ek olarak istek başlıklarını (header) ve yol, sorgu (query) ya da gövde (body) parametrelerini de belirtebilirsiniz. API; yanıt durum kodunu, yanıt başlıklarını ve duruma göre bir yanıt gövdesini döndürür.

API Temel URL'si

Tüm API istekleri için temel URL:
https://api.segmenthub.com

Panel URL'si

Kullanıcı ekleme/çıkarma, medya yükleme, API token'ı oluşturma, rapor ve kampanya oluşturma ya da kitle yönetimi gibi tüm yönetim ihtiyaçlarınız için panel adresi:
https://panel.segmenthub.com

Kimlik Doğrulama & Token'lar

REST API işlemlerinin birçoğuna kimlik doğrulaması olmadan erişilebilir. Ancak bazı işlemler kimlik doğrulaması gerektirir ya da kimliğiniz doğrulandığında ek bilgi döndürür. İsteğinize bir token ekleyerek kimliğinizi doğrulayabilirsiniz. Token edinmek için panele gidin ve erişim yetkilerini ya da limitlerini belirleyerek bir API token'ı oluşturun. Bir ziyaretçinin veya profilin verisini doğrudan değiştirmek için token gereklidir.

Modüller Hakkında

  • DMP: anonim olsun ya da olmasın, tüm ziyaretçilerinizin (cihazların) davranışlarını takip eder.
  • CDP: tanınan bir kullanıcının birden fazla cihazdaki davranışlarını birleştirir.
  • Ad Server: en iyi teklifleri göstermek için ziyaretçinin ilgi alanlarına göre kampanyalar döndürür.

API Yanıt Kodları

Bu API aşağıdaki hata kodlarını kullanır:

  • 200 OK: İstek başarıyla tamamlandı.
  • 400 Bad Request: İstek hatalı biçimlendirilmiş ya da zorunlu parametreler eksik.
  • 401 Unauthorized: Gönderilen API token'ı geçersiz ya da eksik.
  • 403 Forbidden: İstemcinin bu içeriğe erişim yetkisi yok.
  • 404 Not Found: İstenen hesap bulunamadı ya da askıya alınmış.
  • 415 Unsupported Media Type: API yalnızca application/json biçimindeki istekleri işler.
  • 500 Internal Server Error: Sunucuda beklenmeyen bir hata oluştu.
POST /campaigns/query

Olaylar - Sayfa Görüntüleme

Bir sayfa görüntüleme olayı tetikler ve kullanıcı için uygun kampanyaları döndürür.

Gövde Parametreleri

  • account Zorunlu

    Hesabın UUID'si.

  • visitorId Zorunlu

    Ziyaretçinin SDK tarafından oluşturulan (UUID4 biçiminde) visitorId değeri.

  • profileId İsteğe bağlı

    Kullanıcının profileId değeri (e-posta, telefon, userId vb.).

  • platform Zorunlu

    Web sitenizin veya mobil uygulamanızın platform kodu. Örnek: www.example.com

  • device İsteğe bağlı

    Geçerli kullanıcının cihaz türü (desktop, tablet veya mobile).

  • event Zorunlu

    Panel'de Events menüsü altında oluşturulan olay türü.

  • path İsteğe bağlı

    Web sitesinde geçerli sayfanın yolu, mobil uygulamalarda ise ekranın (view) adı.

  • referrer İsteğe bağlı

    Ziyaretçinin geldiği yönlendiren (referrer) URL.

Request Body application/json 
{
    "account": "{{account}}",
    "visitorId": "{{visitorId}}",
    "profileId": "{{profileId}}",
    "platform": "{{platform}}",
    "device": "mobile",
    "event": "pageView",
    "path": "/",
    "referrer": null
}
Response 200 OK 
{
    "status": 200,
    "message": "Campaigns executed successfully.",
    "campaigns": []
}
POST /campaigns/query

Olaylar - Ürün Görüntüleme

Bir ürün görüntüleme olayı tetikler ve kullanıcı için uygun kampanyaları döndürür. (Ortak alanları Sayfa Görüntüleme olayından devralır.)

Ürün Parametreleri

  • sku Zorunlu

    Görüntülenen ürünün SKU bilgisi.

  • price İsteğe bağlı

    Ürünün fiyat bilgisi (ABD sayı biçiminde; ondalık ayırıcı nokta).

  • brand İsteğe bağlı

    Ürünün marka bilgisi.

  • breadcrumb İsteğe bağlı

    Breadcrumb (kategori yolu) bilgisi.

  • category İsteğe bağlı

    Ürünün kategori bilgisi.

Request Body 
{
    "account": "{{account}}",
    "visitorId": "{{visitorId}}",
    "profileId": "{{profileId}}",
    "platform": "{{platform}}",
    "device": "mobile",
    "event": "productView",
    "path": "/",
    "referrer": null,
    "sku": "PRODUCT_SKU_HERE",
    "price": 99.90,
    "brand": "PRODUCT_BRAND_HERE",
    "breadcrumb": "PRODUCT_BREADCRUMB_HERE",
    "category": "PRODUCT_CATEGORY_HERE"
}
POST /campaigns/query

Olaylar - Satın Alma

Bir satın alma olayı tetikler ve kullanıcı için uygun kampanyaları döndürür.

Satın Alma Parametreleri

  • orderId Zorunlu

    Satın alınan ürünlere ait sipariş numarası.

  • orderTotal İsteğe bağlı

    Satın alınan ürünlerin sipariş toplamı.

  • purchasedItems İsteğe bağlı

    Satın alınan ürünlerin SKU'larından oluşan dizi.

Request Body 
{
    "account": "{{account}}",
    "visitorId": "{{visitorId}}",
    "profileId": "{{profileId}}",
    "platform": "{{platform}}",
    "device": "mobile",
    "event": "purchase",
    "path": "/",
    "referrer": null,
    "orderId": "ORDER_ID_HERE",
    "orderTotal": 199.90,
    "purchasedItems": ["SKU1_HERE", "SKU1_HERE"]
}
POST /profiles/query

Profiller - Sorgulama

Belirtilen profilin istenen özniteliklerini ve segmentlerini döndürür.

Gövde Parametreleri

  • account Zorunlu
  • token Zorunlu

    Panel'de Account -> API Tokens sayfasından oluşturulan token.

  • profileId Zorunlu
  • attributes İsteğe bağlı

    İstenecek özniteliklerin dizisi. Bu özniteliklere ilgili token için izin verilmiş olmalıdır.

  • segments İsteğe bağlı

    İstenecek segmentlerin dizisi.

Request Body 
{
    "account": "{{account}}",
    "token": "{{token}}",
    "profileId": "{{profileId}}",
    "attributes": [
        "country",
        "firstName",
        "lastName",
        "lastViewedProducts"
    ],
    "segments": ["VIP", "Churn"]
}
Response 200 OK 
{
    "status": 200,
    "message": "Profile queried successfully.",
    "errors": [],
    "attributes": {
        "country": [{"value": "us"}],
        "firstName": [{"value": "John"}],
        "lastName": [{"value": "Doe"}],
        "lastViewedProducts": [
            {"value": "SKU1"},
            {"value": "SKU2"}
        ]
    },
    "segments": ["VIP"]
}
POST /profiles/attributes

Profiller - Öznitelikleri Güncelleme

Belirtilen profilin istenen özniteliklerini günceller.

Gövde Parametreleri

  • attributes Zorunlu

    Güncellenecek öznitelikleri içeren sözlük (dictionary). İstenen özniteliklere token için izin verilmiş olmalıdır.

Request Body 
{
    "account": "{{account}}",
    "profileId": "{{profileId}}",
    "token": "{{token}}",
    "attributes": {
        "firstName": "Test",
        "lastName": "User",
        "email": "{{profileId}}"
    }
}
Response 200 OK 
{
    "status": 200,
    "profileId": "YOUR_PROFILE_ID",
    "message": "Profile attributes saved successfully.",
    "errors": []
}
POST /profiles/segments

Profiller - Segmentleri Güncelleme

Belirtilen profile segment atar veya profilden segment kaldırır.

Gövde Parametreleri

  • assignees İsteğe bağlı

    Profile atanacak segmentlerin listesi.

  • removes İsteğe bağlı

    Profilden kaldırılacak segmentlerin listesi.

Request Body 
{
    "account": "{{account}}",
    "profileId": "{{profileId}}",
    "token": "{{token}}",
    "assignees": [
        "SEGMENT_TO_BE_ASSIGNED"
    ],
    "removes": [
        "SEGMENT_TO_BE_REMOVED"
    ]
}
POST /visitors/query

Ziyaretçiler - Sorgulama

Belirtilen ziyaretçinin (anonim kullanıcı) istenen özniteliklerini ve segmentlerini döndürür.

Not: profileId yerine visitorId gerektirir.

Request Body 
{
    "account": "{{account}}",
    "token": "{{token}}",
    "visitorId": "{{visitorId}}",
    "attributes": ["country"],
    "segments": ["VIP"]
}
POST /visitors/attributes

Ziyaretçiler - Öznitelikleri Güncelleme

Belirtilen ziyaretçinin istenen özniteliklerini günceller.

Request Body 
{
    "account": "{{account}}",
    "visitorId": "{{visitorId}}",
    "token": "{{token}}",
    "attributes": {
        "gender": "Man",
        "favoriteBrands": ["Nike", "adidas"]
    }
}
POST /visitors/segments

Ziyaretçiler - Segmentleri Güncelleme

Belirtilen anonim ziyaretçiye segment atar veya ziyaretçiden segment kaldırır.

Request Body 
{
    "account": "{{account}}",
    "visitorId": "{{visitorId}}",
    "token": "{{token}}",
    "assignees": [
        "SEGMENT_TO_BE_ASSIGNED"
    ],
    "removes": [
        "SEGMENT_TO_BE_REMOVED"
    ]
}