در ایجاد تعامل با کاربر چابک علاوه بر پنل وب، API‌ هم در اختیار شما قرار می‌دهد. در این صفحه راهنمای استفاده صحیح و آسان برای ارسال پیام و نوتیفیکیشن از طریق API را با هم بررسی خواهیم کرد.


نکته: برای ایجاد دسترسی (Access Token) راهنمای استفاده را مطالعه کنید.

نکته: توجه داشته باشید که پیام چابک به طور پیش‌فرض شامل نوتیفیکیشن هم می‌شود. برای اطلاعات بیشتر درباره تفاوت پیام چابک و نوتیفیکیشن این قسمت را مطالعه کنید.


ارسال شخصی


این قسمت مخصوص ارسال تراکنشی یا تعامل یک به یک با کاربر است. پیام شخصی به شما امکان می‌دهد به یک یا چند شناسه کاربری (userId) پوش بفرستید:

POST | ارسال شخصی پیام چابک

برای ارسال شخصی پیام چابک می‌توانید از لینک https://sandbox.push.adpdigital.com/api/push/toUsers استفاده کنید.

نمونه زیر یک cURL معتبر است:

curl -X POST \
"https://sandbox.push.adpdigital.com/api/push/toUsers?access_token=<ACCESS_TOKEN>" \
-H "accept: application/json" \
-H "Content-Type: application/json" \
-d '{
  "user": "USER_ID",
  "content": "Test webpush",
  "channel": "default",
  "data": {
      "key": "value1",
      "key2": "value2"
  },
  "notification": {
    "title": "عنوان نوتیفیکیشن شما",
    "body": "این یک متن تستی هست که بتونیم باهاش بررسی کنیم آیا بدنه نوتیفیکیشن به خوبی نمایش داده میشه یا نه!",
    "mediaUrl": "https://github.com/chabokpush/chabok-assets/raw/master/samples/notification/chabokpush_twitter.jpeg",
    "vibrate": [10, 20, 30, 40],
    "sound": "toy.mp3",
    "dir": "rtl",
    "color" : "#FF0000",
    "largeIcon": "https://raw.githubusercontent.com/chabok-io/chabok-assets/master/sdk-logo/Android.png",
    "chromeBadge": "https://github.com/chabokpush/chabok-assets/raw/master/chaboklogowhite.png",
    "actions":[{
    	"id": "sent",
    	"title": "Message sent",
    	"icon":  "https://github.com/chabokpush/chabok-assets/raw/master/chaboklogowhite.png",
    	"url": "https://www.google.com"
    },
    {
    	"id": "reply",
    	"action": "reply",
    	"title": "Reply",
    	"icon":  "https://github.com/chabokpush/chabok-assets/raw/master/chaboklogowhite.png"
    }]
  }
}'
جدول پارامترها

پارامترهاتوضیحنوع مقدارمثال
User *شناسه کاربر ثبت شده یا * برای کانال عمومیstringuserTest
channelکانال ارسال پیامstringdefault
content *متن پیامstringسلام
dataدیتای پیام به صورت jsonJSON{"offer": "10", "discountCode": "Newapp10"}
trackIdتعیین شناسه ردگیری جداگانه برای رصد پیامstringadp-1397-6-11
inAppکاربران در زمان باز بودن برنامه پیام را دریافت می‌کنند (درون‌برنامه‌ای)booleantrue
autoNotifyنمایش پیام توسط گوگل صورت می‌گیردbooleanfalse
liveفقط کاربرانی که در لحظه ارسال، برنامه را باز دارند دریافت می‌کنند (زنده)booleanfalse
useAsAlertاستفاده متن پیام به عنوان متن نوتیفیکیشنbooleantrue
alertTextاستفاده از متن جداگانه برای نوتیفیکیشنstringسلام خوبی
ttlزمان انقضای پیام پس از درخواست (ثانیه)number40
fallbackپیامک جایگزینJSON{ "content": "سلام", "delay": 5, "media": "sms" }
clientIdشناسه‌ای که کلاینت برای رصد پیام تعیین می‌کندstringgybpq0458
notificationتنظیمات نوتیفیکیشنpayloadمثال در جدول زیر
silentپیام بدون نوتیفیکیشن ارسال شودbooleanfalse

نکته : نماد * در جدول پارامترها به معنی الزامی بودن پارامتر است و بدون آن‌ درخواست شما صورت نمی‌گیرد.

نکته: نام کانال به صورت پیش‌فرض به عنوان کانال عمومی (public) در نظر گرفته می‌شود و اگر شما می‌خواهید به کاربر روی کانال شخصی پوش ارسال کنید باید قبل از نام کانال عبارت /private را اضافه نمایید. دقت کنید که کاربر یا کاربرانی که می‌خواهید برایشان پوش ارسال کنید روی کانالی که می‌فرستید حتما عضو باشند.


جدول پارامترهای نوتیفیکیشن

پارامترهاتوضیحنوع مقدارمثال
title *عنوان نوتیفیکیشنstringثبت درخواست
bodyمتن نوتیفیکیشنstringسفارش شما ثبت شد
groupIdبرای گروه‌بندی شخصی نوتیفیکیشن‌هاstringnews
iconتصویر نوتیفیکیشنstringنام تصویر
soundصدای نوتیفیکیشن (به فرمت صدا دقت داشته باشید)stringنام صدا
clickUrlلینک هنگام کلیکstringلینک
ledColorتنظیم رنگ led (فقط اندروید)stringکد رنگ HEX
smallIconآیکون کوچک نوتیفیکیشن (فقط اندروید)stringنام آیکون
actionsدکمه (اکشن)arrayآرایه‌ای از جدول زیر
mediaTypeنوع رسانهstringjpeg
mediaUrlلینک رسانهstringلینک
contentAvailableبرای انجام یک آپدیت بی‌صدا در بک‌گراند یا فورگراند مقدار 1 را بگذاریدboolean1
mutableContentبرای پشتیبانی از نوتیفیکیشن چندرسانه‌ای مقدار 1 را حتما قرار دهیدboolean1
categoryشناسه نوتیفیکیشن برای ذخیره آنstringdelivery

پارامترهاتوضیحنوع مقدارمثال
(id (actionشناسه اکشنstringforecast_action
(title (actionعنوان اکشنstringپیش‌بینی کن
(options (actionرفتار اکشن (فقط آی‌او‌اس)number1
(icon (actionنام آیکون در فولدر drawable (فقط اندروید)stringنام آیکون
(url (actionلینک مقصد یا دیپ لینکstringstarter:/detail?id=123

نکته : نماد *در جدول پارامترها به معنی الزامی بودن پارامتر است و بدون آن‌ درخواست شما صورت نمی‌گیرد.

نکته : در پارامترهای نوتیفیکیشن، پارامتر options یا همان رفتار اکشن (فقط در آی‌او‌اس) می‌توانید عدد ۱ برای اکشن Authentication Required (اکشن در صورت قفل نبودن دستگاه اجرا می‌شود)،‌ ۲ برای اکشن Destructive (اکشن تسک مخرب انجام می‌دهد)، ۴ برای اکشن Foreground (اکشن موجب باز شدن اپ در فورگراند می‌شود) و جمع این اعداد را برای ترکیب آن‌ها با هم قرار دهید.

مثال ارسال شخصی پیام چابک به یک کاربر

نمونه زیر یک cURL معتبر از ارسال پیام چابک به یک کاربر (با شناسه کاربری Test) است:

curl -X POST \
"https://sandbox.push.adpdigital.com/api/push/toUsers?access_token=<ACCESS_TOKEN>" \
-H "accept: application/json" \
-H "Content-Type: application/json" \
-d "{ \"user\": \"Test\", \"content\": \"پرواز شما دچار نیم ساعت تاخیر شده است.\", \"useAsAlert\": true}"
مثال ارسال شخصی پیام چابک به چند کاربر با یک محتوا

برای ارسال پیام چابک به به چند شناسه کاربری می‌توانید از روش زیر استفاده کنید:

پی‌لود:

{
  "users": ["USER_1", "USER_2", "USER_3", "USER_4"],
  "content": "سفارش شما با موفقیت ثبت شد",
  "channel": "default",
  "notification": {
   "title": "چابک",
   "body": "سفارش ثبت شد"
  }
}

برای ارسال با پی‌لود بالا cURL زیر را در ترمینال اجرا کنید:

curl -X POST "https://sandbox.push.adpdigital.com/api/push/toUsers?access_token=<ACCESS_TOKEN>" -H "accept: application/json" -H "Content-Type: application/json" \
-d "{ \"users\": [\"USER_1\", \"USER_2\", \"USER_3\", \"USER_4\"], \"content\": \"سفارش شما با موفقیت ثبت شد\", \"channel\": \"default\", \"notification\": { \"title\": \"چابک\", \"body\": \"سفارش ثبت شد\" } }"
مثال ارسال شخصی پیام چابک به چند کاربر با محتواهای متفاوت

برای ارسال پیام چابک به به چند شناسه کاربری با محتواهای متفاوت می‌توانید از روش زیر استفاده کنید:

پی‌لود:

[
  {
    "user": "USER_1",
    "content": "سفارش شما با موفقیت ثبت شد",
    "channel": "default",
    "notification": {
      "title": "چابک",
      "body": "سفارش ثبت شد"
    }
  },
  {
    "user": "USER_2",
    "content": "سفارش شما با موفقیت ثبت شد",
    "channel": "default",
    "notification": {
      "title": "چابک",
      "body": "سفارش ثبت شد"
    }
  },
  {
    "user": "USER_2",
    "content": "سفارش شما با موفقیت ثبت شد",
    "channel": "default",
    "notification": {
      "title": "چابک",
      "body": "سفارش ثبت شد"
    }
  }
]

برای ارسال با پی‌لود بالا cURL زیر را در ترمینال اجرا کنید:

curl -X POST "https://sandbox.push.adpdigital.com/api/push/toUsers?access_token=<ACCESS_TOKEN>" -H "accept: application/json" -H "Content-Type: application/json" \
-d [ "{ \"user\": \"USER_1\", \"content\": \"سفارش شما با موفقیت ثبت شد\", \"channel\": \"default\", \"notification\": { \"title\": \"چابک\", \"body\": \"سفارش ثبت شد\" } }, { \"user\": \"USER_2\", \"content\": \"سفارش شما با موفقیت ثبت شد\", \"channel\": \"default\", \"notification\": { \"title\": \"چابک\", \"body\": \"سفارش ثبت شد\" } }, { \"user\": \"USER_2\", \"content\": \"سفارش شما با موفقیت ثبت شد\", \"channel\": \"default\", \"notification\": { \"title\": \"چابک\", \"body\": \"سفارش ثبت شد\" } }" ]

POST | ارسال شخصی نوتیفیکیشن

برای ارسال شخصی نوتیفیکیش می‌توانید از لینک https://sandbox.push.adpdigital.com/api/push/notifyUsers استفاده کنید.

نمونه زیر یک cURL معتبر است:

curl -X POST \
"https://sandbox.push.adpdigital.com/api/push/notifyUsers?access_token=<ACCESS_TOKEN>" \
-H "accept: application/json" \
-H "Content-Type: application/json" \
-d '{
  "user": "USER_ID",
  "content": "Test webpush",
  "data": {
      "key": "value1",
      "key2": "value2"
  },
  "notification": {
    "title": "عنوان نوتیفیکیشن شما",
    "body": "این یک متن تستی هست که بتونیم باهاش بررسی کنیم آیا بدنه نوتیفیکیشن به خوبی نمایش داده میشه یا نه!",
    "mediaUrl": "https://github.com/chabokpush/chabok-assets/raw/master/samples/notification/chabokpush_twitter.jpeg",
    "vibrate": [10, 20, 30, 40],
    "sound": "toy.mp3",
    "dir": "rtl",
    "color" : "#FF0000",
    "largeIcon": "https://raw.githubusercontent.com/chabok-io/chabok-assets/master/sdk-logo/Android.png",
    "chromeBadge": "https://github.com/chabokpush/chabok-assets/raw/master/chaboklogowhite.png",
    "actions":[{
    	"id": "sent",
    	"title": "Message sent",
    	"icon":  "https://github.com/chabokpush/chabok-assets/raw/master/chaboklogowhite.png",
    	"url": "https://www.google.com"
    },
    {
    	"id": "reply",
    	"action": "reply",
    	"title": "Reply",
    	"icon":  "https://github.com/chabokpush/chabok-assets/raw/master/chaboklogowhite.png"
    }]
  }
}'

نکته: متد ارسال نوتیفیکیشن پی‌لودهای ارسال پیام چابک را پشتیبانی می‌کند، بنابراین می‌توانید از مثال‌های آن استفاده کنید و فقط کافیست متد را از toUsers به notifyUsers تغییر دهید.




ارسال گروهی

این قسمت مخصوص ارسال گروهی یا اجرای کمپین است. پیام گروهی به شما امکان می‌دهد به یک سگمنتی (سگمنت‌ آی‌دی یا فیلترهای سگمنت) پوش بفرستید:

برای مشاهده نحوه استفاده از سگمنت اینجا را مطالعه کنید.

POST | ارسال گروهی پیام چابک

برای ارسال شخصی پیام چابک می‌توانید از لینک https://sandbox.push.adpdigital.com/api/push/byQuery استفاده کنید.

نمونه زیر یک cURL معتبر است:

curl -X POST \
"https://sandbox.push.adpdigital.com/api/push/byQuery?access_token=<ACCESS_TOKEN>" \
-H "accept: application/json" \
-H "Content-Type: application/json" \
-d "{\"segment\": { \"all\": [ { \"name\": \"deviceType\", \"operator\": \"include\", \"value\": [ \"android\", \"ios\" ] }, { \"name\": \"tags\", \"operator\": \"include\", \"value\": [ \"FEMALE\" ] }, { \"name\": \"purchase.count\", \"operator\": \"greater_than\", \"value\": 1 } ] },\"content\": \"خریدهای عیدتان را از همین الان شروع کنید!\",\"useAsAlert\": \"true\"}"
جدول پارامترها

پارامترهاتوضیحنوع مقدارمثال
target *ویژگی‌های گروه‌بندیobject{"target":{ "deviceType": "ios" }}
channelکانال ارسال پیامstringdefault
content *متن پیامstringسلام
dataدیتای پیام به صورت jsonJSON{"offer": "10", "discountCode": "Newapp10"}
trackIdتعیین شناسه ردگیری جداگانه برای رصد پیامstringadp-1397-6-11
inAppکاربران در زمان باز بودن برنامه پیام را دریافت می‌کنند (درون‌برنامه‌ای)booleantrue
liveفقط کاربرانی که در لحظه ارسال، برنامه را باز دارند دریافت می‌کنند (زنده)booleanfalse
autoNotifyنمایش پیام توسط گوگل صورت می‌گیردbooleanfalse
useAsAlertاستفاده متن پیام به عنوان متن نوتیفیکیشنbooleantrue
alertTextاستفاده از متن جداگانه برای نوتیفیکیشنstringسلام خوبی
ttlزمان انقضای پیام پس از درخواست (ثانیه)number40
notificationتنظیمات نوتیفیکیشنpayloadمثال در جدول زیر
silentپیام بدون نوتیفیکیشن ارسال شودbooleanfalse

نکته : نماد * در جدول پارامترها به معنی الزامی بودن پارامتر است و بدون آن‌ درخواست شما صورت نمی‌گیرد.

نکته: نام کانال به صورت پیش‌فرض به عنوان کانال عمومی (public) در نظر گرفته می‌شود و اگر شما می‌خواهید به کاربر روی کانال شخصی پوش ارسال کنید باید قبل از نام کانال عبارت /private را اضافه نمایید. دقت کنید که کاربر یا کاربرانی که می‌خواهید برایشان پوش ارسال کنید روی کانالی که می‌فرستید حتما عضو باشند.


جدول پارامترهای نوتیفیکیشن

پارامترهاتوضیحنوع مقدارمثال
title *عنوان نوتیفیکیشنstringثبت درخواست
bodyمتن نوتیفیکیشنstringسفارش شما ثبت شد
groupIdبرای گروه‌بندی شخصی نوتیفیکیشن‌هاstringnews
iconتصویر نوتیفیکیشنstringنام تصویر
soundصدای نوتیفیکیشن (به فرمت صدا دقت داشته باشید)stringنام صدا
clickUrlلینک هنگام کلیکstringلینک
ledColorتنظیم رنگ led (فقط اندروید)stringکد رنگ HEX
smallIconآیکون کوچک نوتیفیکیشن (فقط اندروید)stringنام آیکون
actionsدکمه (اکشن)arrayآرایه‌ای از جدول زیر
mediaTypeنوع رسانهstringjpeg
mediaUrlلینک رسانهstringلینک
contentAvailableبرای انجام یک آپدیت بی‌صدا در بک‌گراند یا فورگراند مقدار 1 را بگذاریدboolean1
mutableContentبرای پشتیبانی از نوتیفیکیشن چندرسانه‌ای مقدار 1 را حتما قرار دهیدboolean1
categoryشناسه نوتیفیکیشن برای ذخیره آنstringdelivery

پارامترهاتوضیحنوع مقدارمثال
(id (actionشناسه اکشنstringforecast_action
(title (actionعنوان اکشنstringپیش‌بینی کن
(options (actionرفتار اکشن (فقط آی‌او‌اس)number1
(icon (actionنام آیکون در فولدر drawable (فقط اندروید)stringنام آیکون
(url (actionلینک مقصد یا دیپ لینکstringstarter:/detail?id=123

نکته : نماد * در جدول پارامترها به معنی الزامی بودن پارامتر است و بدون آن‌ درخواست شما صورت نمی‌گیرد.

نکته : در پارامترهای نوتیفیکیشن، پارامتر options یا همان رفتار اکشن (فقط در آی‌او‌اس) می‌توانید عدد ۱ برای اکشن Authentication Required (اکشن در صورت قفل نبودن دستگاه اجرا می‌شود)،‌ ۲ برای اکشن Destructive (اکشن تسک مخرب انجام می‌دهد)، ۴ برای اکشن Foreground (اکشن موجب باز شدن اپ در فورگراند می‌شود) و جمع این اعداد را برای ترکیب آن‌ها با هم قرار دهید.

مثال ارسال گروهی پیام چابک

نمونه زیر یک cURL معتبر از ارسال پیام چابک گروهی است. گروه مخاطب این پیام، خانم‌هایی هستند که بیش از یک بار خرید داشته‌اند و از موبایل (دستگاه‌های اندروید و آی‌اواس) استفاده می‌کنند.

curl -X POST \
"https://sandbox.push.adpdigital.com/api/push/byQuery?access_token=<ACCESS_TOKEN>" \
-H "accept: application/json" \
-H "Content-Type: application/json" \
-d "{\"segment\": { \"all\": [ { \"name\": \"deviceType\", \"operator\": \"include\", \"value\": [ \"android\", \"ios\" ] }, { \"name\": \"tags\", \"operator\": \"include\", \"value\": [ \"FEMALE\" ] }, { \"name\": \"purchase.count\", \"operator\": \"greater_than\", \"value\": 1 } ] },\"content\": \"خریدهای عیدتان را از همین الان شروع کنید!\",\"useAsAlert\": \"true\"}"

POST | ارسال گروهی نوتیفیکیشن

برای ارسال گروهی نوتیفیکیش می‌توانید از لینک https://sandbox.push.adpdigital.com/api/push/notifyUsers استفاده کنید.

نمونه زیر یک cURL معتبر است:

curl -X POST \
"https://sandbox.push.adpdigital.com/api/push/notifyUsers?access_token=<ACCESS_TOKEN>" \
-H "accept: application/json" \
-H "Content-Type: application/json" \
-d "{\"segment\": { \"all\": [ { \"name\": \"deviceType\", \"operator\": \"include\", \"value\": [ \"android\", \"ios\" ] }, { \"name\": \"tags\", \"operator\": \"include\", \"value\": [ \"FEMALE\" ] }, { \"name\": \"purchase.count\", \"operator\": \"greater_than\", \"value\": 1 } ] },\"content\": \"خریدهای عیدتان را از همین الان شروع کنید!\",\"useAsAlert\": \"true\"}"

نکته: متد ارسال نوتیفیکیشن پی‌لودهای ارسال پیام چابک را پشتیبانی می‌کند، بنابراین می‌توانید از مثال‌های آن استفاده کنید و فقط کافیست متد را از byQuery به notifyUsers تغییر دهید.





نحوه استفاده از سگمنت‌ها در API

هر سگمنت می‌تواند شامل یک یا چند شرط (rule) باشد.

شرط‌ها

هر شرط شامل ۳ قسمت اصلی می‌باشد:

  • name: نام فیلد

  • operator: نوع عملوند (مانند بزرگتر، مساوی‌ با و غیره)

  • value: مقداری که سنجش می‌شود

عملوند‌های مجاز (operators)

  • equal_to: برابر با

  • not_equal: برابر نباشد با

  • lesser_than: کوچکتر از

  • lesser_equals: کوچکتر مساوی

  • greater_than: بزرگتر از

  • greater_equals: بزرگتر مساوی

  • include: یکی از

  • not_include: هیچکدام از

  • before: قبل از

  • after: بعد از

نکته: عملوند‌های before و after مخصوص فیلد‌هایی از جنس زمان هستند، و مقداری که در قسمت value این نوع شرط‌ها قرار میگیرد به صورت xh می‌باشد. نمونه: 'value: '6h.

nameهای مجاز

  • installDate: زمان اولین بازدید

  • launchTime: زمان آخرین بازدید

  • launchCount: تعداد بازدید

  • tags: تگ‌های کاربر

  • deviceType: نوع دستگاه

  • clientVersion: نسخه برنامه

  • osVersion: نسخه سیستم‌عامل

مثال زیر کاربرانی را هدف قرار می‌دهد که بعد از ۶ ساعت پیش، برنامه‌ را نصب کرده‌اند و بیش از ۲ بار هم آن را باز نموده‌اند:

نمونه

"segment": {
  "all": [
    {
       "name": "installDate",
       "operator": "after",
       "value": "6h"
    },
    {
       "name": "launchCount",
       "operator": "greater_than",
       "value": 2
    }
  ]
}