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

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

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

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

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

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

مخاطبان ایمیل

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

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

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

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

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

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

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

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

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

// minimum required keys
{
  "app_ids": ["YOUR_APP_ID"],
  "data": {
    "isHTML":false,
    "subject":"عنوان ایمیل",
    "content":"سلام خسته نباشید<br/><br/>این یک ایمیل تستی می‌یاشد."
  },
  "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 برابر یک دیکشنری خالی باشد، پیام برای تمامی کاربران شما ارسال خواهد شد.

ارسال ایمیل با محتوای HTML

در صورتی که می‌خواهید محتوای ایمیل HTML باشد، کافیست کدهای HTML را در قالب string به عنوان مقدار کلید content قرار دهید. همچنین برای اینکار باید کلید isHTML را برابر مقدار true فرار دهید.`

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

برای قرار دادن new line در متن ایمیل کافیست از تگ <br/> همانند زیر استفاده کنید.

{
  "data":{
    "content":"سلام خسته نباشید<br/><br/>این یک ایمیل تستی می‌یاشد."
  }
}

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

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

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

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

• شناسه یکتا 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/email/ \
-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": {"subject": "عنوان پیام", "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/email/`;

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

const data = {
    app_ids: YOUR_APP_ID,
    data: {
        subject: 'عنوان پیام',
        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/email/'

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

payload = json.dumps({
    'app_ids': YOUR_APP_ID,
    'data': {
        'subject': 'عنوان اعلان',
        '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/email/');

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(
        'subject' => 'عنوان پیام',
        '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/email/"

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