ارسال‌ پیام چابک

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


ارسال به یک کاربر به خصوص (toUsers)

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

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


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

لینک پایه: 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

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

پارامترها توضیح نوع مقدار مثال
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

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

نکته : در پارامترهای اعلان، پارامتر 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 توجه فرمایید:

درخواست

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

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

عکس مربوطه

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




ارسال به گروهی از کاربران (byQuery)

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

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

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

پاسخ

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

{
  "count": number
}



مثال

به مثال زیر از متد byQuery توجه فرمایید:

درخواست

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

نکته : در قسمت سگمنت، فیلترهای پیش‌فرض چابک ‍‍‍‍‍‍‍‍‍‍‍‍‍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
    }
  ]
}

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