ارسال اعلان فیلتردار به کاربر(های) اپلیکیشن

تعریف اعلان فیلتردار

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

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

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

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

تعریف شناسه‌های یکتا در ارسال اعلان

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

• شناسه یکتا device_id:
  iOS

  Android
  • اندروید: این شناسه توسط اندروید به کاربران اختصاص داده می‌شود و در واقع معادل Android Id می‌باشد. در گوشی‌های با سیستم عامل پایین‌تر از اندروید ۸، شناسه‌ی Android ID کاربر بین تمامی اپلیکیشن‌های نصب شده بر روی گوشی ثابت است و همچنین پس از حذف و نصب مجدد اپلیکیشن نیز ثابت می‌ماند. در نسخه‌ی اندروید ۸ به بالا، شناسه‌ی Android ID یک کاربر تنها برای اپلیکیشن‌هایی که با کلید‌های یکسان امضا شده باشند یکتا است و برای بقیه‌ی اپلیکیشن‌ها متفاوت است.
  • آی‌او‌اس: شناسه‌ای است که توسط آی‌او‌اس به یک اپلیکیشن داده می‌شود و به ازای یک vendor یکتا می‌باشد. این شناسه متناظر با identifierForVendor در آی‌او‌اس می‌باشد.

• شناسه یکتا android_id:
  iOS

  Android
  • اندروید: متناظر با مقدار شناسه device_id است.
  • آی‌او‌اس: شاید استفاده از این کلید در پلتفرم آی‌او‌اس ارتباط مفهومی با این پلتفرم نداشته باشد ولی با توجه به اینکه قصد داشتیم استفاده از وب سرویس برای همه پلتفرم‌ها به یک شکل واحد باشد به ناچار از این کلید برای فیلتر کردن دستگاه‌های آی‌او‌اس هم مورد استفاده قرار می‌گیرد و مقدار آن برابر با مقدار کلید device_id است.

• شناسه یکتا ad_id:

  iOS

  Android
  • اندروید: این شناسه را Google Play Services به کاربران اختصاص می‌دهد و در واقع معادل همان Advertising ID می‌باشد. شناسه Advertising ID کاربر بین تمام اپلیکیشن‌های نصب شده بر روی گوشی او ثابت است ولی کاربر قادر است که این شناسه را reset و یا غیر فعال کند.
  • آی‌او‌اس: شناسه‌ای است که توسط آی‌اواس داده می‌شود و در بین تمامی اپلیکیشن‌ها با vendor های متفاوت یکسان می‌باشد. کاربر می‌تواند استفاده از این شناسه را غیرفعال یا مقدار آن را ریست کند. این شناسه متناظر با advertisingIdentifier می‌باشد.

• شناسه یکتا phone_number:

  Android
  • شماره تلفن کاربر
  • مقدار: لیستی از رشته‌‌ها
  • مثال:["09*********", "09*********"]
  • راهنمای تخصیص این شناسه در کتابخانه پوشه

• شناسه یکتا email:

  Android
  • آدرس ایمیل کاربر
  • مقدار: لیستی از رشته‌‌ها
  • مثال:["[email protected]", "[email protected]"]
  • راهنمای تخصیص این شناسه در کتابخانه پوشه

• شناسه یکتا custom_id:

  Android
  • هر عبارت دلخواهی که می‌خواهید به عنوان شناسه استفاده کنید
  • مقدار: لیستی از رشته‌‌ها
  • مثال:["custom_id1", "custom_id2"]
  • راهنمای تخصیص این شناسه در کتابخانه پوشه

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

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

{
    "filters": {
        "device_id": ["list of device ids or android ids ..."],
        "android_id": ["list of device ids or android ids ..."],
        "ad_id": ["list of ad_ids ..."],
        "phone_number": ["list of device ids or phone_numbers ..."],
        "email": ["list of device ids or emails ..."],
        "custom_id": ["list of custom_ids ..."]
    }
}

نکته مهم

دو کلید یکتای android_id و device_id در وب سرویس پوشه مقادیر یکسانی رو دریافت می‌کنند.

نکته مهم

پوشه استفاده از کلید device_id را برای ارسال اعلان‌های فیلتردار توصیه می‌کند.

تعریف فیلترهای ارسال اعلان

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

• فیلتر operator: این کلید برای مشخص کردن نوع اپراتور می‌باشد
  • مقادیر:ir-mci‍‍, irancell, rightel
• فیلتر brand: این کلید برای فیلتر کردن بر اساس انواع برند دستگاه می باشد
  • مقادیر:samsung, LGE, asus, htc, lenovo, sony, huawei
• فیلتر mobile_net: این کلید بیانگر نوع اینترنت می‌باشد
  • مقادیر: ‍lte, wifi
• فیلتر state: این فیلتر برای مشخص کردن استان می‌باشد
  • مقادیر:East Azerbaijan , Azarbayjan-e Gharbi , Ardabil , Isfahan , Alborz , Ilam , Bushehr , Tehran , Chahar Mahall va Bakhtiari, Khorasan-e Jonubi , Razavi Khorasan , Khorasan-e Shomali , Khuzestan , Zanjan , Semnan , Sistan and Baluchestan , Fars, Qazvin , Qom , Kordestan , Kerman , Kermanshah , Kohgiluyeh va Buyer Ahmad , Golestan , Gilan , Lorestan , Mazandaran, Markazi , Hormozgan , Hamadan , Yazd

علاوه بر این هم می توانید از فیلتر app_version برای مشخص کردن مخاطبین اعلان استفاده کنید.

• فیلتر app_version: برای فیلتر کردن بر اساس ورژن اپلیکیشن‌تان
  • مقدار: مقدار قابل قبول لیستی از ورژن‌های اپلیکیشن به شکل رشته string می باشد. برای مثال: ["1.0.1", "1.0.2"]

همچنین شما می‌توانید با استفاده از کلید tags برای کاربران خود اعلان ارسال کنید. برای دریافت اطلاعات بیشتر از نحوه برچسب‌گذاری (Tag) کاربران می‌توانید به بخش برچسب‌گذاری در مستندات کتابخانه پوشه مراجعه کنید.

• فیلتر tags: برای فیلتر کردن بر اساس برچسب(Tag)
  • مقدار: مقدار قابل قبول دیکشنری‌ای از کلید‌ها و مقادیر ‌آنها به شکل رشته string می باشد. برای مثال: {"name":"Mohammad", "age":"25"}

نکته مهم

در مثال قبل مخاطبان اعلان شما کسانی خواهند بود که همزمان دو برچسب ذکر شده را داشته باشند.

در زیر و در قالب json نحوه قرار دادن فیلترهای ذکر شده در داخل کلید filters نمایش داده شده.

{
    "filters": {
        "operator": ["ir-mci‍‍", "irancell"],
        "brand": ["asus", "sony"],
        "mobile_net": ["wifi"],
        "state", ["list of states ..."],
        "app_version": ["1.0.0"],
        "tags": {"name":"Mohammad", "age":"25"}
    }
}

آدرس (url) ارسال اعلان

برای ارسال اعلان فیلتردار می‌توانید از آدرس زیر که برای ارسال اعلان به پلتفرم‌های آی‌او‌اس و اندروید می‌باشد استفاده کنید. https://api.pushe.co/v2/messaging/notifications/

نمونه کد ارسال اعلان فیلتردار

برای مشاهده تمامی کلید های قابل استفاده در ارسال اعلان به بخش تمامی کلید های اعلان مراجعه کنید.

CURL

• در این نمونه کد از cURL استفاده شده است که می‌توانیدتوسط sudo apt install curl آن را نصب کنید.

curl -X POST https://api.pushe.co/v2/messaging/notifications/ \
-H 'authorization: Token YOUR_TOKEN' \
-H 'content-type: application/json' \
-d '{
"app_ids": "YOUR_APP_ID", 
"filters": {
    "device_id": ["device_id_1","device_id_3", "device_id_2", "device_id_4"], 
    "brand": ["samsung", "sony"], 
    "app_version": ["1.0.1", "1.0.2"]
}, 
"data": {"title": "عنوان پیام", "content": "محتوای پیام"}
}'

NODE.JS

• برای اجرای این کد باید ابتدا پکیج axios را نصب کنید ‍npm install axios

const axios = require('axios');

const YOUR_TOKEN = 'put your token here ...';
const YOUR_APP_ID = 'put your app id here ...';

const url = `https://api.pushe.co/v2/messaging/notifications/`;

const options = {
    headers: {
        'Authorization': `Token ${YOUR_TOKEN}`,
        'Content-Type': 'application/json'
    }
};

const data = {
    app_ids: YOUR_APP_ID,
    data: {
        title: 'عنوان پیام',
        content: 'متن پیام'
    },
    filters: {
        device_id: [
            'device_id_1', 
            'device_id_2', 
            'device_id_3', 
            'device_id_4'
        ],
        brand: ['samsung', 'sony'],
        app_version: ['1.0.1', '1.0.2']
    }
};

axios.post(url, data, options)
    .then(resp => console.log(resp))
    .catch(err => console.error(err));

PYTHON

• برای اجرا نیاز به پایتون ورژن ۳.۶ و به بالا می‌باشد
• برای اجرای این کد باید ابتدا پکیج requests را نصب کنید. pip install requests

import requests
import json

YOUR_TOKEN = 'put your token here ...'
YOUR_APP_ID = 'put your app id here ...'

url = f'https://api.pushe.co/v2/messaging/notifications/'

headers = {
    'Authorization': f'Token {YOUR_TOKEN}',
    'Content-Type': 'application/json'
}

payload = json.dumps({
    'app_ids': YOUR_APP_ID,
    'data': {
        'title': 'عنوان اعلان',
        'content': 'متن اعلان'
    },
    'filters': {
        'device_id': [
            'device_id_1', 
            'device_id_2', 
            'device_id_3', 
            'device_id_4'
        ],
        'brand': ['samsung', 'sony'],
        'app_version': ['1.0.1', '1.0.2']
    }
})

r = requests.post(url, data=payload, headers=headers)

print(r.status_code)

PHP

$YOUR_TOKEN = 'put your token here ...';
$YOUR_APP_ID = 'put your app id here ...';

$ch = curl_init('https://api.pushe.co/v2/messaging/notifications/'); 

curl_setopt_array($ch, array(
    CURLOPT_POST  => 1,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => array(
        "Content-Type: application/json",
        "Authorization: Token " . $YOUR_TOKEN,
    ),
));

curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(array(
    'app_ids' => $YOUR_APP_ID,
    'data' => array(
        'title' => 'عنوان پیام',
        'content' => 'متن پیام'
    ),
    'filters' => array(
        'device_id' => array(
            'device_id_1', 
            'device_id_2', 
            'device_id_3', 
            'device_id_4'
        ),
        'brand' => array(
            'samsung', 
            'sony'
        ),
        'app_version' => array(
            '1.0.1', 
            '1.0.2'
        )
    )
)));

$result = curl_exec($ch);
 
curl_close($ch);

echo $result;

GO

package main

import (
    "fmt"
    "bytes"
    "io/ioutil"
    "encoding/json"
    "net/http"
)

const YOUR_TOKEN = "put your token here ..."
const YOUR_APP_ID = "put your app id here ..."

func main() {
    url := "https://api.pushe.co/v2/messaging/notifications/"

    payload := map[string]interface{}{
        "app_ids" : YOUR_APP_ID,
        "data": map[string]string{
            "title": "عنوان اعلان",
            "content": "متن اعلان",
        },
        "filters": map[string][]string{
            "device_id": []string{
                "device_id_1", 
                "device_id_2", 
                "device_id_3", 
                "device_id_4"
            },
            "brand": []string{
                "samsung", 
                "sony"
            },
            "app_version": []string{
                "1.0.1", 
                "1.0.2"
            },
        }
    }

    jsonValue, _ := json.Marshal(payload)

    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonValue))

    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("Authorization", "Token " + YOUR_TOKEN)

    client := &http.Client{}
    resp, err := client.Do(req)

    if err != nil {
        panic(err)
    }

    defer resp.Body.Close()

    fmt.Println("response Status:", resp.Status)
    body, _ := ioutil.ReadAll(resp.Body)
    fmt.Println("response Body:", string(body))
}