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

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

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