ارسال‌ پوش

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


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


ارسال شخصی


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

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

برای ارسال شخصی پیام چابک می‌توانید از لینک 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 "@payload.json"
جدول پارامترها

پارامترها توضیح نوع مقدار مثال
User * شناسه کاربر ثبت شده یا * برای کانال عمومی string userTest
channel کانال ارسال پیام string default
content * متن پیام string سلام
data دیتای پیام به صورت json JSON {"offer": "10", "discountCode": "Newapp10"}
trackId تعیین شناسه ردگیری جداگانه برای رصد پیام string adp-1397-6-11
inApp کاربران در زمان باز بودن برنامه پیام را دریافت می‌کنند (درون‌برنامه‌ای) boolean true
autoNotify نمایش پیام توسط گوگل صورت می‌گیرد boolean false
live فقط کاربرانی که در لحظه ارسال، برنامه را باز دارند دریافت می‌کنند (زنده) boolean false
useAsAlert استفاده متن پیام به عنوان متن نوتیفیکیشن boolean true
alertText استفاده از متن جداگانه برای نوتیفیکیشن string سلام خوبی
ttl زمان انقضای پیام پس از درخواست (ثانیه) number 40
fallback پیامک جایگزین JSON { "content": "سلام", "delay": 5, "media": "sms" }
clientId شناسه‌ای که کلاینت برای رصد پیام تعیین می‌کند string gybpq0458
notification تنظیمات نوتیفیکیشن payload مثال در جدول زیر
silent پیام بدون نوتیفیکیشن ارسال شود boolean false

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

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


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

پارامترها توضیح نوع مقدار مثال
title * عنوان نوتیفیکیشن string ثبت درخواست
body متن نوتیفیکیشن string سفارش شما ثبت شد
groupId برای گروه‌بندی شخصی نوتیفیکیشن‌ها string news
icon تصویر نوتیفیکیشن string نام تصویر
sound صدای نوتیفیکیشن (به فرمت صدا دقت داشته باشید) string نام صدا
clickUrl لینک هنگام کلیک string لینک
ledColor تنظیم رنگ led (فقط اندروید) string کد رنگ HEX
smallIcon آیکون کوچک نوتیفیکیشن (فقط اندروید) string نام آیکون
(id (action شناسه اکشن string check
(title (action عنوان اکشن string status
(options (action رفتار اکشن (فقط آی‌او‌اس) number 1
(icon (action نام آیکون در فولدر drawable (فقط اندروید) string نام آیکون
mediaType نوع رسانه string jpeg
mediaUrl لینک رسانه string لینک
contentAvailable برای انجام یک آپدیت بی‌صدا در بک‌گراند یا فورگراند مقدار 1 را بگذارید boolean 1
mutableContent برای پشتیبانی از نوتیفیکیشن چندرسانه‌ای مقدار 1 را حتما قرار دهید boolean 1
category شناسه نوتیفیکیشن برای ذخیره آن string delivery

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

نکته : در پارامترهای نوتیفیکیشن، پارامتر 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\": \"سفارش ثبت شد\" } }" ]


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

برای ارسال شخصی نوتیفیکیش می‌توانید از لینک 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 "@payload.json"

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




ارسال گروهی

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

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

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

برای ارسال شخصی پیام چابک می‌توانید از لینک 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 "@payload.json"
جدول پارامترها

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

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

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


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

پارامترها توضیح نوع مقدار مثال
title * عنوان نوتیفیکیشن string ثبت درخواست
body متن نوتیفیکیشن string سفارش شما ثبت شد
groupId برای گروه‌بندی شخصی نوتیفیکیشن‌ها string news
icon تصویر نوتیفیکیشن string نام تصویر
sound صدای نوتیفیکیشن (به فرمت صدا دقت داشته باشید) string نام صدا
clickUrl لینک هنگام کلیک string لینک
ledColor تنظیم رنگ led (فقط اندروید) string کد رنگ HEX
smallIcon آیکون کوچک نوتیفیکیشن (فقط اندروید) string نام آیکون
(id (action شناسه اکشن string check
(title (action عنوان اکشن string status
(options (action رفتار اکشن (فقط آی‌او‌اس) number 1
(icon (action نام آیکون در فولدر drawable (فقط اندروید) string نام آیکون
mediaType نوع رسانه string jpeg
mediaUrl لینک رسانه string لینک
contentAvailable برای انجام یک آپدیت بی‌صدا در بک‌گراند یا فورگراند مقدار 1 را بگذارید boolean 1
mutableContent برای پشتیبانی از نوتیفیکیشن چندرسانه‌ای مقدار 1 را حتما قرار دهید boolean 1
category شناسه نوتیفیکیشن برای ذخیره آن string delivery

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

نکته : در پارامترهای نوتیفیکیشن، پارامتر 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\"}"


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

برای ارسال گروهی نوتیفیکیش می‌توانید از لینک 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 "@payload.json"

نکته: متد ارسال نوتیفیکیشن پی‌لودهای ارسال پیام چابک را پشتیبانی می‌کند، بنابراین می‌توانید از مثال‌های آن استفاده کنید و فقط کافیست متد را از 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
    }
  ]
}