API custom_data ile mesajları kişiselleştirin

• Mesaja özeldir
• Saklanmaz
• Yalnızca API isteği sırasında mevcuttur
• Bir template_id ile kullanılmalıdır

{{ message.custom_data.key_name }}

​

custom_data ne zaman kullanılır

• Veriler mesaj başına değişiyorsa (sipariş toplamları, sepet ürünleri, bakiyeler)
• Dizilere ihtiyacınız varsa (ürün listeleri, satır öğeleri, öneriler)
• Veriler kalıcı olmamalıysa (tek kullanımlık kodlar, geçici URL’ler)
• Arka uçtan tetiklenen mesajlar gönderiyorsanız
• Tek bir API isteğinde toplu kişiselleştirme yapmak istiyorsanız

​

custom_data kişiselleştirmesi nasıl çalışır

Hi {{ message.custom_data.first_name }},
Order {{ message.custom_data.order_id }} is confirmed.

​

Veri kalıpları

​

Düz JSON örneği

Invoice {{ message.custom_data.invoice_id }} for {{ message.custom_data.product_name }} is ready.

{
  "app_id": "YOUR_APP_ID",
  "template_id": "YOUR_TEMPLATE_ID",
  "include_email_tokens": ["user@example.com"],
  "custom_data": {
    "invoice_id": "463246732",
    "product_name": "Widget"
  }
}

Invoice 463246732 for Widget is ready.

​

Dizi verisi örneği

Your {{message.custom_data.cart_items[0].item_name}} is waiting for you!
Image: {{message.custom_data.cart_items[0].img_url}}

{% for item in message.custom_data.cart_items %}
- {{ item.item_name }} — {{ item.img_url }}
{% endfor %}

{
  "app_id": "YOUR_APP_ID",
  "template_id": "YOUR_TEMPLATE_ID",
  "include_email_tokens": ["user@example.com"],
  "custom_data": {
    "cart_items": [
      {
        "item_name": "sweater",
        "img_url": "https://.../sweater.png"
      },
      {
        "item_name": "socks",
        "img_url": "https://.../socks.png"
      }
    ]
  }
}

Your sweater is waiting for you!
Image: https://.../sweater.png

- sweater — https://.../sweater.png
- socks — https://.../socks.png

• {{message.custom_data.cart_items.size}} — Dizideki öğe sayısı (bu örnekte 2 döndürür)
• {{message.custom_data.cart_items.first.item_name}} — İlk öğenin adı ([0] ile eşdeğer)
• {{message.custom_data.cart_items.last.item_name}} — Son öğenin adı

​

Toplu kişiselleştirme örneği

1. custom_data yapısını anahtarların external_id’ler, değerlerin kullanıcıya özel veriler olduğu bir nesne olarak oluşturun
2. Şablonda, geçerli alıcının verilerini aramak için subscription.external_id kullanın
3. OneSignal, şablonu her alıcı için kendi özel verileriyle bir kez render eder

{% assign user = message.custom_data.users[subscription.external_id] %}
Hi {{ user.first_name }}, you have {{ user.points }} points. Your level is {{ user.level }}.

• subscription.external_id geçerli alıcının external_id değerini içerir (ör. “user123”)
• message.custom_data.users[subscription.external_id] custom_data nesnesinden o kullanıcının verilerini arar
• user, o kullanıcının verileri için bir kısayol değişkeni olur
• Her alıcı yalnızca kendi kişiselleştirilmiş içeriğini görür

{
  "app_id": "YOUR_APP_ID",
  "template_id": "YOUR_TEMPLATE_ID",
  "include_aliases": {
    "external_id": ["user123", "user456"]
  },
  "custom_data": {
    "users": {
      "user123": { "first_name": "John", "points": "150", "level": "Gold" },
      "user456": { "first_name": "Sarah", "points": "200", "level": "Platinum" }
    }
  }
}

​

Örnek: custom_data ile terk edilmiş sepet

• Sunucunuz sepet terkini algıladığında (ör. son aktiviteden 1 saat sonra)
• Gerçek zamanlı sepet verileri veritabanınızda olduğunda
• Resimler, isimler, fiyatlarla birden fazla ürün görüntülemek istediğinizde
• Her kullanıcının farklı ürünleri ve miktarları olabildiğinde
• Mesajı arka uçunuzdan yönetmek istediğinizde

​

Örnek custom_data payload

{
  "custom_data": {
    "cart_url": "https://yourdomain.com/cart",
    "cart": [
      {
        "product_name": "24 Pack of Acorns",
        "product_image": "https://i.imgur.com/ssPCfbC.png",
        "product_price": "$12.99",
        "product_quantity": "1"
      },
      {
        "product_name": "Fancy Sweater",
        "product_image": "https://i.imgur.com/8QWTfV4.png",
        "product_price": "$9.99",
        "product_quantity": "1"
      }
    ]
  },
  "app_id": "YOUR_APP_ID",
  "template_id": "YOUR_TEMPLATE_ID",
  "include_aliases": {
    "external_id": ["YOUR_EXTERNAL_ID"]
  }
}

​

E-posta şablonu

• Sepet öğe sayısı
• Bir for-döngüsü kullanarak her ürünü resim, ad, miktar ve fiyatla birlikte
• Müşterinin benzersiz sepet URL’sine bağlanan bir buton

1

E-posta şablonunu oluşturun

Messages > Templates > New Email Template bölümüne gidin ve Sürükle ve Bırak Düzenleyiciyi açın.

2

Düzen yapısını ekleyin

Beş satır oluşturun:

• Satır 1, 2 ve 4: Paragraph bloğu olan tek sütun
• Satır 3: HTML | Paragraph | Paragraph | Paragraph olan dört sütun
• Satır 5: Button bloğu olan tek sütun

3

Öğe sayısını görüntüleyin

Satır 1’e şunu ekleyin:

Liquid

We're holding onto {{message.custom_data.cart.size}} items in your cart, but don't wait too long, other squirrels are getting ahead!

Daha iyi dilbilgisi için “1 item” ve “2 items” şeklinde koşullu ifade kullanabilirsiniz, ancak terk edilmiş sepet e-postaları için çoğul genellikle kabul edilebilir.

Liquid

{% assign cart = message.custom_data.cart %}
{% assign item_count = cart.size | plus: 0 %}
{% if item_count == 1 %}
We're holding onto {{item_count}} item in your cart, but don't wait too long, other squirrels are getting ahead!
{% endif %}
{% if item_count > 1 %}
We're holding onto {{item_count}} items in your cart, but don't wait too long, other squirrels are getting ahead!
{% endif %}

4

Döngüyü başlatın

Sepetteki her öğe için ürün görüntüleme satırını tekrarlamak üzere bir for-döngüsü kullanın.Satır 2’de (döngü başlangıcı) Metin bloğuna şunu ekleyin:

Text

{% for product in message.custom_data.cart %}

Bunun yaptığı:

• cart dizisindeki her nesne üzerinde yineleme yapan bir döngü başlatır
• Geçerli öğeyi temsil eden product adında geçici bir değişken oluşturur
• {% for %} ve {% endfor %} arasındaki her şey sepet öğesi başına bir kez tekrarlanır
• product yerine herhangi bir isim verebilirsiniz (ör. item, cartItem)—sadece tutarlı olun

For-döngüsü yerleşimi: {% for %} söz diziminin kendi Metin bloğu satırında olduğundan emin olun. Diğer içeriklerle birlikte çok sütunlu bir satırın içine koymayın, bu bazı istemcilerde e-posta render’ını bozabilir.

5

Ürün detaylarını görüntüleyin

Bu 4 sütunlu satır resim, ad, miktar ve fiyatı gösterir. Döngünün içinde olduğu için her sepet öğesi için tekrarlanır.Satır 3’te (ürün detayları) yapılandırın:Sütun 1 - HTML bloğu (ürün görseli):

HTML

<img src="{{product.product_image}}" alt="Product image" style="max-width:100%;" />

Sütun 2–4 - Metin blokları (ürün adı, miktar, fiyat):

• Sütun 2: {{product.product_name}}
• Sütun 3: {{product.product_quantity}}
• Sütun 4: {{product.product_price}}

Döngü nasıl çalışır:

• İlk yinelemede, product = sepet dizisindeki ilk nesne
• {{product.product_image}} ilk öğenin resim URL’sini alır
• İkinci yinelemede, product = ikinci nesne
• Satır tüm sepet öğeleri için otomatik olarak tekrarlanır

Alan adı eşleştirmesi: product_image gibi anahtarlar, olay payload’ınızla tam olarak eşleşmelidir (büyük/küçük harfe duyarlı). Eşleşmeyenler boş dize olarak render edilir.

6

Döngüyü sonlandırın

Tekrarlamanın nerede durduğunu belirlemek için döngüyü kapatın.Satır 4’te (döngü sonu) şunu ekleyin:

Liquid

{% endfor %}

Her {% for %} ifadesinin eşleşen bir {% endfor %} ifadesi olmalıdır. Bu eksik olursa e-posta render’ı bozulur.

7

Sepet bağlantı butonu ekleyin

Satır 5’teki Button bloğunda Action URL değerini ayarlayın:

Text

{{message.custom_data.cart_url}}

8

Şablonu test edin

• Örnek custom_data payload kullanarak API isteğinizi ayarlayın
• Kendinize e-postayı gönderin.
• Verilerin doğru görüntülendiğini doğrulayın.

Başarılı! Artık şablona kendi stilinizi uygulayabilirsiniz. Sürükle ve bırak ile e-posta tasarlama bölümüne bakın.

​

Push şablonu

{% assign cart = message.custom_data.cart %}
{% assign item_count = cart.size | plus: 0 %}
{% if item_count == 1 %}
You left {{cart.first.product_name}} in your cart.
{% endif %}
{% if item_count == 2 %}
You left {{cart.first.product_name}} and {{item_count | minus: 1}} more item in your cart.
{% endif %}
{% if item_count > 2 %}
You left {{cart.first.product_name}} and {{item_count | minus: 1}} more items in your cart.
{% endif %}

{{message.custom_data.cart.first.product_image | default: "https://i.imgur.com/ssPCfbC.png"}}

{{cart_url | default: "https://yourdomain.com/cart"}}

​

Sorun giderme ve en iyi uygulamalar

• Basit tutun: Yalnızca şablonda gerçekten kullanacağınız verileri dahil edin
• 2KB altında kalın: Özellikle dizilerde payload boyutunuzu izleyin
• Tutarlı adlandırma kullanın: Baştan sona snake_case veya camelCase kullanın
• Göndermeden önce doğrulayın: Null değerleri, boş dizileri ve gerekli alanları kontrol edin

• İsteğe bağlı alanlar için her zaman default filtreleri kullanın:
  Liquid

  {{message.custom_data.user_name | default: "there"}}
  
• Döngü yapmadan önce dizi boyutunu kontrol edin:
  Liquid

  {% if message.custom_data.items.size > 0 %}
    {% for item in message.custom_data.items %}
      {{item.name}}
    {% endfor %}
  {% endif %}
  
• Uç durumlarla test edin: boş diziler, eksik alanlar, maksimum öğe sayıları

• Doğrulama hatalarını yakalamak için API yanıtlarını sunucu tarafında kaydedin
• Mesaj teslim oranlarını izleyin—ani düşüşler Liquid hatalarına işaret edebilir
• Kritik işlemsel mesajlar için yedek şablonları hazır bulundurun

• Karmaşık Liquid mantığı kullanmak yerine karmaşık verileri arka uçunuzda önceden biçimlendirin
• Şablonları önbelleğe alın ve birçok API çağrısında yeniden kullanın
• Yüksek hacimli işlemsel mesajları pazarlama kampanyalarından ayırmayı düşünün

​

İlgili sayfalar