ارسال‌ پوش

در این صفحه راهنمای استفاده صحیح و آسان برای ارسال پوش از طریق API را با هم بررسی خواهیم کرد. برای این کار دو متد post (پست) toUsers و byQuery وجود دارد که در ادامه به هر دوی آن‌ها خواهیم پرداخت.

ارسال پوش از طریق کانال‌های چابک

در این متد (toUsers) می‌توانیم برای یک یک یا چند کاربر بخصوص یا همه کاربران یک کانال پیامی را از طریق API ارسال کنیم. (پیام خصوصی و عمومی)

ساختار درخواست

لینک پایه: 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
live فقط کاربرانی که در لحظه ارسال، برنامه را باز دارند دریافت می‌کنند (زنده) boolean false
useAsAlert استفاده متن پیام به عنوان متن اعلان boolean true
alertText استفاده از متن جداگانه برای اعلان string سلام خوبی
ttl زمان انقضای پیام پس از درخواست (ثانیه) number 40
fallback پیامک جایگزین JSON { "content": "سلام", "delay": 5, "media": "sms" }
notification تنظیمات اعلان payload مثال در جدول زیر
silent پیام بدون اعلان ارسال شود boolean false

پارامترهای اعلان (Notification)

پارامترها توضیح نوع مقدار مثال
title عنوان اعلان string ثبت درخواست
body متن اعلان string سفارش شما ثبت شد
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 (اکشن موجب باز شدن اپ در فورگراند می‌شود) و جمع این اعداد را برای ترکیب آن‌ها با هم قرار دهید.

نکته : برای ارسال پیام به چند کاربر با متد toUsers می‌توانید از دو روش استفاده کنید. روش اول قرار دادن آرایه‌ای از شناسه‌های کاربری در فیلد users (نه user) و روش دوم ایجاد کردن payloadهای مورد نظر به ازای هر کاربر و ارسال همه آن‌ها می‌باشد. به نمونه زیر توجه فرمایید:

نمونه روش اول:

{
  "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": "سفارش ثبت شد"
    }
  }
]

پاسخ

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

{
  "count": number
}



مثال از متد toUsers

درخواست

نکته : از پارامتر‌هایی که در این عمل استفاده می‌شوند، user و content (شناسه کاربر و محتوای پیام) الزامی هستند و بدون آن‌ها درخواست شما صورت نمی‌گیرد. (برای پیام عمومی در قسمت user به جای شناسه کاربر، استریسک(*) را وارد نمایید.)

بسته به نوع پیامی که می‌خواهید ارسال کنید می‌توانید از انواع پارامترها استفاده کنید. به عنوان مثال می‌خواهیم یک پیامی برای هشدار یک کاربر با userId (شناسه کاربری) 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}"

پاسخ

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

{
  "count": 1
}

حالا می‌توانید در پنل بخش پیام‌ها قسمت پیام‌ها جزئیات ارسال و تحویل پیام خود را مشاهده کنید.

عکس مربوطه

نکته : برای تست کردن این عمل می‌توانید به این لینک مراجعه فرمایید.



ارسال پوش از طریق گروه‌بندی کاربران (Segmented Push)

در این متد (byQuery) به جای ارسال پیام به صورت خصوصی یا عمومی می‌خواهیم به گروهی از کاربران ارسال کنیم. برای آشنایی با نحوه استفاده از سگمنت در API لطفا راهنمای آن را مطالعه نمایید.

ساختار درخواست

لینک پایه: 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
useAsAlert استفاده متن پیام به عنوان متن اعلان boolean true
alertText استفاده از متن جداگانه برای اعلان string سلام خوبی
ttl زمان انقضای پیام پس از درخواست (ثانیه) number 40
notification تنظیمات اعلان payload مثال در جدول زیر
silent پیام بدون اعلان ارسال شود boolean false

پارامترهای اعلان (Notification)

پارامترها توضیح نوع مقدار مثال
title عنوان اعلان string ثبت درخواست
body متن اعلان string سفارش شما ثبت شد
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 (اکشن موجب باز شدن اپ در فورگراند می‌شود) و جمع این اعداد را برای ترکیب آن‌ها با هم قرار دهید.

پاسخ

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

{
  "count": number
}



مثال از متد byQuery

درخواست

اکنون می‌خواهیم کمپینی را بسازیم و گروهی از کاربران را براساس ویژگی‌های مورد نظر‌ (سگمنت) مخاطب قرار دهیم. به عنوان مثال این کمپین به مناسبت راه‌افتادن اپلیکیشن موبایل در آی‌ا‌و‌اس می‌خواهد کد تخفیفی را مخصوص کسانی که اپلیکیشن شما را در موبایل خود دارند، ارسال کند. متن پیام هم می‌خواهیم به عنوان متن اعلان به کار برده شود.

نکته : از پارامتر‌هایی که در این عمل استفاده می‌شوند، target و content (ویژگی‌های گروه و محتوای پیام) الزامی هستند و بدون آن‌ها درخواست شما صورت نمی‌گیرد.

نکته : در قسمت سگمنت، فیلترهای پیش‌فرض چابک ‍‍‍‍‍‍‍‍‍‍‍‍‍installDate (اولین بازدید یا نصب) ، launchTime (آخرین بازدید) ،‌ launchCount (تعداد بازدید) ، clientVersion (نسخه برنامه) ،‌ osVersion (نسخه سیستم‌عامل) ، deviceType (نوع دستگاه) ، tags (تگ‌ها) ، nearBy (موقعیت مکانی) می‌باشند. درصورت اضافه کردن سگمنت از سوی خودتان هم فقط کافی‌‌ست نام آن را وارد نمایید.

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 "{\t\"target\": {\t\t\"deviceType\": \"ios\"\t},\t\"content\": \"سلام به اپلیکیشن ما خوش‌آمدید. برای خرید اولتان از اپلیکیشن می‌توانید از کد تخفیف 10٪ استفاده کنید. کد تخفیف: NewApp10\",\t\"useAsAlert\": true}"

پاسخ

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

{
  "count": 44
}

پس از ارسال موفقیت آمیز می‌توانید در پنل بخش کمپین‌ها آمار ارسال و تحویلتان را مشاهده کنید.

عکس مربوطه

نکته : برای تست کردن این عمل می‌توانید به این لینک مراجعه فرمایید.

نحوه استفاده از سگمنت‌ها در 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
    }
  ]
}

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