Shopify Mağaza Uygulamaları İçin Entegrasyon

Bu rehber, Shopify mağazası için mobil uygulaması olan ekipler içindir. Uygulama Storefront API, Customer Account API veya Checkout Kit ile Expo, React Native, Flutter ya da native olarak geliştirilmiş olabilir. Genel API referansı için Genel bakış.

Bu rehber, platform kurulumunun üzerine Shopify'a özel adımları anlatır: müşteri eşleştirme, e-ticaret attributes'ları, backend (webhook) güncellemeleri ve kampanya kurguları.

Desteklenen sürümler: Shopify Storefront API ve Customer Account API'nin desteklenen tüm sürümleri (örnekler 2025-01 ve sonrası ile uyumludur) · Mobil taraf için ilgili platform rehberindeki sürümler.

Uygulamanız Tapcart, Shopney, Plobal gibi kodsuz bir uygulama oluşturucu ile yapıldıysa, NotiPilot entegrasyonu için uygulamaya özel kod ekleyebilmeniz gerekir. Bu platformların özel kod/SDK desteği olup olmadığını sağlayıcınıza danışın.

#1. Önce platform entegrasyonu

Mobil uygulamanızın teknolojisine göre cihaz kaydını kurun:

Bu adım bittiğinde her cihaz NotiPilot'ta kayıtlı ve "Tüm kullanıcılar" gönderimlerini alıyor olmalıdır.

#2. Müşteriyi cihazla eşleştirme

Müşteri uygulamada giriş yaptığında identify-device çağırın. external_id olarak Shopify müşteri ID'sini önekle birlikte kullanın:

gid://shopify/Customer/7234567890123  →  external_id: "shopify:7234567890123"

Önek (shopify:), ileride başka kaynaklardan gelen kullanıcı ID'leriyle çakışmayı önler.

#Storefront API ile müşteri bilgisini almak

query Customer($token: String!) {
  customer(customerAccessToken: $token) {
    id
    acceptsMarketing
    defaultAddress { city countryCodeV2 }
  }
}

Yeni Customer Account API kullanıyorsanız: customer { id defaultAddress { city territoryCode } emailAddress { marketingState } }

#identify-device çağrısı (TypeScript örneği)

async function identifyShopifyCustomer(customer: {
  id: string;
  acceptsMarketing: boolean;
  defaultAddress?: { city?: string | null; countryCodeV2?: string | null } | null;
}) {
  const numericId = customer.id.split('/').pop(); // "gid://shopify/Customer/123" → "123"

  await fetch('https://app.notipilot.com/api/v1/identify-device', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      app_id: 'EXPO-PROJE-ID-NIZ',
      device_uid: await getDeviceUid(),          // platform rehberindeki fonksiyon
      external_id: `shopify:${numericId}`,
      consent_marketing: customer.acceptsMarketing,
      attributes: {
        customer_type: 'registered',
        country: customer.defaultAddress?.countryCodeV2 ?? null, // "TR"
        city: customer.defaultAddress?.city ?? null,             // "Istanbul"
      },
    }),
  });
}

Müşteri çıkış yaptığında register-device isteğini "external_id": null ve "attributes": { "customer_type": "guest" } ile tekrar gönderin.

Konum segmentleri için önemli: Müşterinin varsayılan teslimat adresindeki city ve countryCodeV2, NotiPilot'taki konum segmentlerinin en güvenilir kaynağıdır. Giriş yapmamış kullanıcılar için en azından cihaz bölgesinden country gönderin.

#3. Önerilen e-ticaret attributes'ları

NotiPilot paneli her attribute değeri için otomatik segment üretir. Bu yüzden sınırlı sayıda farklı değer alan alanlar kullanın; sayıları aralıklara bölün.

❌ orders_count: 17, total_spent: 1234.56, e-posta, telefon gibi değerleri göndermeyin: ya çok sayıda anlamsız segment oluşturur ya da kişisel veridir.

tags alanını müşteri tag'lerinden türetilmiş kısa etiketler için kullanabilirsiniz (ör. ["vip", "wholesale"]). tags gönderildiğinde mevcut listenin yerine geçer.

#4. Backend'den güncelleme (Shopify webhook'ları)

NotiPilot API'si sade bir HTTP API'dir; mobil uygulamanın yanı sıra kendi backend'inizden de çağrılabilir. Bunun için müşteri giriş yaptığında device_uid değerini kendi backend'inizde müşteriyle birlikte saklayın. Bir müşterinin birden fazla cihazı olabilir.

Örnek: orders/create webhook'u geldiğinde müşterinin tüm cihazlarını güncelleyin (Node.js):

app.post('/webhooks/orders-create', verifyShopifyHmac, async (req, res) => {
  const order = req.body;
  const customerId = order.customer?.id;
  if (!customerId) return res.sendStatus(200);

  const ordersCount = order.customer.orders_count ?? 1;
  const bucket = ordersCount >= 6 ? '6+' : ordersCount >= 2 ? '2-5' : String(ordersCount);
  const devices = await db.devicesForCustomer(customerId); // [{ device_uid }, ...]

  await Promise.all(devices.map((d) =>
    fetch('https://app.notipilot.com/api/v1/identify-device', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        app_id: process.env.NOTIPILOT_APP_ID,
        device_uid: d.device_uid,
        external_id: `shopify:${customerId}`,
        attributes: {
          orders_bucket: bucket,
          last_order_month: new Date().toISOString().slice(0, 7),
          cart_status: 'empty',
        },
      }),
    })
  ));

  res.sendStatus(200);
});

Faydalı webhook konuları:

Rate limit IP başına dakikada 300 istektir. Toplu güncellemelerde istekleri sıraya koyun ve 429 yanıtında retry_after kadar bekleyin.

#5. Bildirim içeriği ve derin bağlantı

Panelden gönderirken Data alanına uygulamanızın tanıdığı bir yönlendirme bilgisi koyun:

{ "screen": "product", "handle": "kirmizi-elbise" }
{ "screen": "collection", "handle": "yeni-sezon" }
{ "screen": "cart" }

Uygulamada bildirime tıklanma olayında bu alanları okuyup ilgili ekrana yönlendirin (platform rehberlerindeki "bildirime tıklandı" örneklerine bakın). Ürün sayfasını handle ile Storefront API'den çekebilirsiniz: product(handle: "kirmizi-elbise") { ... }.

#6. Kampanya örnekleri

#7. Yasal notlar

• Pazarlama bildirimleri için Shopify'daki pazarlama onayını (acceptsMarketing / marketingState) consent_marketing alanına aktarın.
• Kişisel verileri (e-posta, telefon, adres satırı) attributes'a koymayın; eşleştirme için yalnızca external_id kullanın.
• KVKK / GDPR kapsamında silme talebi gelen müşterinin cihazları için external_id: null gönderip ilgili attributes'ları null ile temizleyin.

#Kontrol listesi

• Platform entegrasyonu tamamlandı (cihazlar kayıtlı)
• Girişte external_id: "shopify:<id>" ile identify-device çağrılıyor
• country ve city varsayılan adresten gönderiliyor
• consent_marketing Shopify pazarlama onayından besleniyor
• Sayısal değerler aralıklara (bucket) bölünüyor
• (İsteğe bağlı) device_uid backend'de saklanıyor ve webhook'larla güncelleme yapılıyor