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

تعریف پیامک فیلتردار

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

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

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

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

مخاطبان پیامک

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

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

آدرس (url) ارسال پیامک

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

https://api.pushe.co/v2/messaging/sms/

کلید‌های ارسال پیامک فیلتردار

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

• app_ids: شناسه اپلیکیشن که از نوع رشته string می‌باشد.
  این فیلد اجباری است
• data: یک دیکشنری که مقادیر (محتوای) پیامک را نگه می‌دارد.
  این فیلد اجباری است
  • content: این فیلد بیانگر متن پیامک می‌باشد و از نوع رشته string می‌باشد.
    این فیلد اجباری است
• filters: یک دیکشنری که مقادیر فیلترهای پیامک را نگه می‌دارد.
  این فیلد اختیاری است

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

{
  "app_ids": ["YOUR_APP_ID"],
  "data": {
    "content":  "متن پیام"
  },
  "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"}
  }
}

فیلتر مخاطبان

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

فیلتر خالی

در صورتی که مقدار کلید filters برابر یک دیکشنری خالی باشد، پیام برای تمامی کاربران شما ارسال خواهد شد.

مرتب ‌سازی متن پیام

برای قرار دادن new line در متن پیامک کافی است از کاراکتر n\ همانند زیر استفاده کنید.

{
  "data":{
    "content":"سلام خسته نباشید \nاین پیامک یک تست می‌باشد"
  }
}

کلید‌های مجاز در وب‌ سرویس پیامک

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

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

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

• شناسه یکتا 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"}
  }
}

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

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

CURL

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

curl -X POST https://api.pushe.co/v2/messaging/sms/ \
-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": {"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/sms/`;

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

const data = {
    app_ids: YOUR_APP_ID,
    data: {
        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/sms/'

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

payload = json.dumps({
    'app_ids': YOUR_APP_ID,
    'data': {
        '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/sms/');

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(
        '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/sms/"

    payload := map[string]interface{}{
        "app_ids" : YOUR_APP_ID,
        "data": map[string]string{
            "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))
}