راهنمای استفاده از API پوش‌پل

امکانات پوش‌پل از طریق پنل پوش‌پل در اختیار شما هستند. اما اگر می خواهید با کدنویسی و بصورت مستقیم از سرور یا اپ خود ارسال پوش را انجام بدهید، می توانید از API پوش‌پل استفاده کنید. آدرس ‍‍API با توجه به پلتفرمی که از آن استفاده می‌کنید متفاوت است لذا در صورتی که قصد استفاده از پلتفرم اندروید را دارید از کلید android و در صورتی که که قصد استفاده از پلتفرم آی او اس را دارید از کلید ios بجای کلید واژه platform در داک استفاده کنید.

احراز هویت

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

برای دریافت Token دائمی خود می‌توانید از قسمت حساب کاربری در کنسول پوش‌پل، توکن خود را دریافت کرده و به جای کلمه‌ی YOUR_SESSION_TOKEN از آن استفاده کنید.

ایجاد اپلیکیشن با استفاده از API پوش‌پل

برای ایجاد اپلیکیشن می‌توانید از آدرس https://api.push-pole.com/v2/applications/{platform}/ بصورت زیر استفاده کنید:

curl -X POST https://api.push-pole.com/v2/applications/{platform}/ -H 'Authorization: Token YOUR_TOKEN' -H 'content-type:application/json' -d '{"package_name": "com.example.app", "name": "example", "framework": 2}'

مقادیر مجاز برای platform می‌تواند android باشد.

پاسخ دریافتی برای درخواست‌‌ ایجاد اپلیکیشن(اندروید و ios) بدین فرمت خواهد بود:

‍‍‍

{
    "name": "APP_NAME",
    "package_name": "PACKAGE_NAME",
    "app_id": "UNIQUE_IDENTIFIER_GENERATED_BY_PUSHPOLE",
    "created_at": "UTC TIMEZONE",
    "framework": "SMALL INTEGER NUMBER",
    "aggregator": "USER INSTANCE",
    "has_one_signal_user": "BOOLEAN FIELD",
    "type": "SMALL INTEGER NUMBER",
    "provider": "PROVIDER INTANCE",
    "credential": {
        "server_key": "SERVER_KEY",
        "client_key": "CLIENT_KEY"
    },
    "active_users": "NUMBER OF ACTIVE USERS"
}

چرا در صورتی که از client_key و server_key خود استفاده نکنید، فقط client_key را دریافت می‌کنیم؟
چون پوش‌پل از client_key و server_key خود برای ارسال اعلان‌‌ها استفاده می‌کند، لذا فقط client_key به شما نمایش داده می‌شود.

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

در قرار دادن کلید Authorization به فاصله بین Token و YOUR_TOKEN توجه کنید.

دریافت لیست اپلیکیشن‌ها استفاده از API پوش‌پل

برای دریافت لیست اپلیکیشن‌های خود می‌توانید از آدرس https://api.push-pole.com/v2/applications/{platform}/ بصورت زیر استفاده نمایید:

curl -X GET https://api.push-pole.com/v2/applications/{platform}/ -H 'Authorization: Token YOUR_TOKEN' -H 'content-type: application/json'

مقادیر مجاز برای platform می‌تواند android و ios باشد.

پاسخ دریافتی برای درخواست‌‌ مشاهده لیست اپلیکیشن‌‌ها(اندروید و ios) بدین فرمت خواهد بود:

[
    {
        "name": "APP_NAME",
        "package_name": "PACKAGE_NAME",
        "app_id": "UNIQUE IDENTIFIER",
        "created_at": "2018-10-13T05:49:28.292622Z",
        "framework": 1,
        "aggregator": null,
        "has_one_signal_user": false,
        "type": 1,
        "provider": null,
        "credential": {
            "server_key": "server_key",
            "client_key": "client_key"
        },
        "active_users": 0,
        "installation_count": 0,
        "owner": "YOUR_EMAIL_ADDRESS",
        "welcome_template": null,
        "update_template": null,
        "welcome_template_v2": null,
        "update_template_v2": null,
        "welcome_active": false,
        "icon_url": "ICON_URL"
    }
]

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

در پوش‌پل بصورت کلی برای تغیر نام اپلیکیشن خود می‌توانید از آدرس https://api.push-pole.com/v2/applications/{platform}/YOUR_APPLICATION_ID/ بصورت زیر استفاده نمایید:

curl -X PATCH https://api.push-pole.com/v2/applications/{platform}/YOUR_APPLICATION_ID/ -H 'Authorization: Token YOUR_TOKEN' -H 'content-type: application/json' -d '{"name": "YOUR_APPLICATION_NAME"}'

مقادیر مجاز برای platform می‌تواند android و ios باشد.

فرمت پاسخ دریافتی بدین صورت خواهد بود:

 {
     "name": "NEW_APP_NAME",
     "package_name": "PACKAGE_NAME",
     "app_id": "UNIQUE IDENTIFIER",
     "created_at": "2018-10-11T13:25:31.050004Z",
     "framework": 4,
     "aggregator": null,
     "has_one_signal_user": false,
     "type": 1,
     "provider": null,
     "credential": {
         "server_key": "server_key",
         "client_key": "client_key"
     },
     "active_users": 0,
     "installation_count": 0,
     "owner": "YOUR_EMAIL_ADDRESS",
     "welcome_template": null,
     "update_template": null,
     "welcome_template_v2": null,
     "update_template_v2": null,
     "welcome_active": false,
     "icon_url": null
 }

حذف اپلیکیشن با استفاده از API در پوش‌پل

در پوش‌پل بصورت کلی برای حذف نام اپلیکیشن خود می‌توانید از آدرس https://api.push-pole.com/v2/applications/{platform}/YOUR_APPLICATION_ID/ بصورت زیر استفاده نمایید:

curl -X DELETE https://api.push-pole.com/v2/applications/{platform}/YOUR_APPLICATION_ID/ -H 'Authorization: Token YOUR_TOKEN' -H 'content-type: application/json'

مقادیر مجاز برای platform می‌تواند android و ios باشد.

دریافت تاریخچه نصب‌های یک اپلیکیشن با استفاده از API در پوش‌پل

برای دریافت تاریخچه نصب‌های یک اپلیکیشن می‌توانید از آدرس https://api.push-pole.com/v2/applications/{platform}/YOUR_APPLICATION_ID/export/ بصورت زیر استفاده کنید:

curl -X POST https://api.push-pole.com/v2/applications/{platform}/YOUR_APPLICATION_ID/export/ -H 'Authorization: Token YOUR_TOKEN' -H 'content-type: application/json' 

مقادیر مجاز برای platform می‌تواند android و ios باشد.

فرمت پاسخ دریافتی بدین صورت خواهد بود:

{
   "result": true
}

ارسال اعلان

ارسال پوش ساده به همه کاربران

برای ارسال یک پوش ساده به همه کاربرانتان میتوانبد از آدرس https://api.push-pole.com/v2/messaging/notifications/ بصورت زیر استفاده کنید:

curl -X POST https://api.push-pole.com/v2/messaging/notifications/ -H 'Authorization: Token YOUR_Session_TOKEN' -H 'content-type: application/json' -d '{"app_ids":["com.exmaple.app"], "data" : {"title":"عنوان اعلان", "content":"محتوای اعلان"}}

فرمت داده‌های ارسالی بدین صورت می‌باشد:

{
  "app_ids": ["com.example.app"],
  "data": {
    "title": "عنوان پیام",
    "content": "محتوای پیام"
  }
}

پاسخ دریافتی برای تمامی درخواست‌های ساخت اعلان به صورت زیر خواهد بود:

{
    "wrapper_id": "UNIQUE IDENTIFIER",
    "hashed_id": "SHARE_URL",
    "app_ids": [
        "com.example.app"
    ],
    "data": {
        "title": "عنوان اعلان",
        "content": "محتوای اعلان"
    },
    "data_type": 1,
    "custom_content": {},
    "abt_ids": null,
    "topics": null,
    "filters": null,
    "exclude_filters": null,
    "rate_limit": null,
    "max_recipients": null,
    "unique": false,
    "statistics": {
        "recipient_count": 0,
        "delivered": 0,
        "clicked": 0,
        "dismissed": 0,
        "nacked": 0,
        "acked": 0
    },
    "type": 2,
    "platform": 1,
    "content_type": 1,
    "priority": null,
    "created_at": "DateTime",
    "dispatch_started_at": null,
    "dispatch_ended_at": null,
    "updated_at": null,
    "time_to_live": 604800,
    "collapse_key": null,
    "eta": null,
    "update_av_code": null,
    "status": 1
}

ارسال تک پیام به کاربران خاص

شما می توانید با استفاده از آدرس https://api.push-pole.com/v2/messaging/notifications/ علاوه بر ارسال اعلان به همه‌ی کاربران، اعلان را به یک یا تعدادی کاربر خاص نیز ارسال کنید. برای این کار لازم است از کاربرانی که می‌خواهید به آن‌ها اعلان ارسال شود شناسه داشته باشید. شناسه‌های زیر را می‌توان برای ارسال اعلان استفاده کرد

برای ارسال اعلان به کاربران خاص موقع ارسال اعلان در فیلد filters نام نوع شناسه‌ای که می‌خواهید از آن استفاده کنید را بگذارید و جلوی آن لیستی از شناسه‌های کاربرانی که می‌خواهید به آن‌ها اعلان ارسال شود را قرار دهید. برای مثال ارسال اعلان به دو کاربر بر اساس Unique Id آن‌ها به صورت زیر خواهد بود:

curl -X POST https://api.push-pole.com/v2/messaging/notifications/ -H 'Authorization: Token YOUR_Session_TOKEN' -H 'content-type: application/json' -d '{"app_ids": ["com.package_name_34"], "filters": {"pushe_id": ["pid_20aa-ba40-a0","pid_39ca-ee30-d9"]}, "data": {"title": "عنوان پیام", "content": "محتوای پیام"}}'

فرمت داده‌های ارسالی بدین صورت می‌باشد:

{
  "app_ids": ["com.example.app"],
  "filters": {
    "pushe_id": ["pid_20aa-ba40-a0","pid_39ca-ee30-d9"]
  },
  "data": {
    "title": "عنوان پیام",
    "content": "محتوای پیام"
  }
}

ارسال یک JSON بدون نمایش اعلان

ممکن است شما بخواهید تنها اطلاعاتی را به اپ منتقل کنید ولی چیزی به کاربر نمایش داده نشود. برای این کار شما باید در اپ خود یک کلاس برای دریافت json اضافه کنید. نحوه انجام این کار در آموزش های ابتدای این صفحه توضیح داده شده است. کلید "Show_app" در data قرار دارد.کاربرد این کلید زمانی است که می خواهید داده ای را به اپلیکیشن منتقل کنید اما به کاربر پوش نمایش داده نشود. اگر مقدار این کلید true (پیش فرض) باشد پوش به کاربر نمایش داده می شود و اگر false باشد فقط داده منتقل می شود و به کاربر پوش نمایش داده نمی شود. برای استفاده از این قابلیت می توانید از آدرس https://api.push-pole.com/v2/messaging/notifications/ بصورت زیر برای ارسال داده استفاده کنید:

curl -X POST https://api.push-pole.com/v2/messaging/notifications/ -H 'Authorization: Token YOUR_Session_TOKEN' -H 'content-type: application/json' -d '{"app_ids": ["com.package_name"], "data": {"show_app": false}, "custom_content": {"key_1": "Value_1","Key_2": "Value_2"}}'

فرمت داده‌های ارسالی بدین صورت می‌باشد:

{
  "app_ids": ["com.example.app"],
  "data": {
    "show_app": false
  },
  "custom_content": {
    "key_1": "Value_1",
    "Key_2": "Value_2", 
    .......
  },
  "priority":2

}

ارسال اعلان تراکنشی (API چابک)

در صورتی که نیازی به ثبت اعلان در پنل و مشاهده‌ی آمار آن ندارید و نیازمندی شما ارسال اعلان به صورت حجیم و سریع است، می‌توانید از روش ارسال اعلان چابک (Rapid APIs) پوش‌پل استفاده کنید. برای استفاده از این ویژگی بایستی درخواست‌های خود را با استفاده از متود POST به درگاه‌های ارسال چابک پوش‌پل در آدرس https://api.push-pole.com/v2/messaging/rapid ارسال کنید. فرمت داده‌ی ارسالی شما بایستی از قالب زیر پیروی کنند.

• در هر درخواست بایستی تنها یک اپلیکیشن آی‌دی مشخص شود.
• گیرندگان اعلان در هر درخواست توسط یکی از سه روش شناسه‌ی تبلیغاتی گوگل (Google Advertisement ID)، شناسه‌ی پوش‌پل (Unique ID) و یا شناسه‌ی اندروید (Android ID) مشخص می‌شوند. دقت کنید که در هر درخواست تنها از یکی از این سه روش برای شناسایی گیرندگان اعلان استفاده می‌شود.
• حداکثر دریافت‌کنندگان یک اعلان در هر درخواست (اندازه‌ی لیست گیرندگان، aids، pids یا gaids) برابر با ۵۰ نصب است.
• در کلید data، مقادیری که توسط کتابخانه‌ی پوش‌پل پذیرفته می‌شوند را قرار دهید. در واقع این کلید رزرو شده برای زمانی است که می‌خواهید اعلانی را با استفاده از امکانات کتابخانه به کاربرانتان نمایش دهید.
• در کلید custom_content می‌توانید هر محتوایی را قرار دهید که به شکل json به دریافت‌کنندای که در برنامه‌ی خود نوشته‌اید تحویل داده می‌شود.

به طور کلی قالب نهایی ارسال این نوع اعلان را در زیر مشاهده می‌کنید.

curl -X POST "https://api.push-pole.com/v2/messaging/rapid/"  -i -H "Authorization: Token 7fb1………………………………29b464c "  -H "Content-Type: application/json" -H "Accept: application/json" --data 'Payload'

{
    "app_id": "com.test.pushpole",

    // One of the following identifiers, use either only G_AID, UniqueID, or AndroidID

    "gaids": [
        "Google Advertisement ID 1",
        "Google Advertisement ID 2",
        "Google Advertisement ID 3",
        "Google Advertisement ID 4"
    ],
    "pids": [
        "PushPole ID 1",
        "PushPole ID 2"
    ],
    "aids": [
        "Android ID 1",
        "Android ID 2"
    ],
    // One of the following, use either data (to use PushPole's SDK features) or custom_content to provide your own JSON

    "data": {
        "title": "Title",
        "content": "Content"
    },
    "custom_content": {
        "1": "2"
    },

    "ttl": 3600 // [int: seconds] Optional, span of time the notification stays alive before being delivered to the user
}

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

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

{
  "app_ids": [
    "com.example.app"
  ],
  "data": {
    "title": "عنوان",
    "content": "تیتر",
    "big_title": "تیتر کامل",
    "big_content": "متن بزرگ",
    "summary": "چکیده ",
    "image": "http://url/name.png",
    "icon": "http://url/name.png",
    "ticker": "متن نوار اعلان",
    "notif_icon": "file_download",
    "wake_screen": true,
    "sound_url": "http://static.push-pole.com/mp3/2.mp3",
    "visibility": true,
    "led_color": "-8206336",
    "show_app": true,
    "led_on": 300,
    "led_off": 500,
    "delay_until": true,
    "action": {
      "url": "tg://join?invite=sdfdsfdsfds",
      "action_type": "U"
    },
    "buttons": [
      {
        "btn_icon": "fileـdownload",
        "btn_order": 1,
        "btn_content": "متن دکمه",
        "btn_action": {
          "url": "tg://join?invite=fdsfdsfds",
          "action_type": "U"
        }
      },
      {
        "btn_icon": "local_cafe",
        "btn_order": 2,
        "btn_content": "متن دکمه",
        "btn_action": {
          "url": "http://fgfdgfdg.com",
          "action_type": "U"
        }
      },
      {
        "btn_icon": "phoneـandroid",
        "btn_order": 3,
        "btn_content": "متن دکمه",
        "btn_action": {
          "url": "call:dddd",
          "action_type": "U"
        }
      }
    ]
  },
  "filters": {
    "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":[
      "1.0", "2.0"
    ]
  },
  "exclude_filters": {
    "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"
    ]
  },
  "collapse_key": "key1",
  "time_to_live": 172800,
  "topics":["topic_name1", ...],
  "unique": true,
  "eta":"2016-10-18T13:28:00+03:30",
  "rate_limit": "بزودی",
  "platform": 1,
  "priority": 1,
  "abt_ids": ["notification_wrapper_id", ...] 
}

همه ی کلیدهای استفاده شده در اعلان پیشرفته در جدول ۱ توضیح داده شده اند.

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

برای دریافت نمونه کد‌های ارسال اعلان برای زبان‌های برنامه‌نویسی php , go, c# , nodejs , python به اینجا مراجعه فرمایید.

جدول ۱. کلیدهای اعلان پیشرفته

بعضی از کلید ها مقدارهای مختلف می گیرند که در جدول ۲ و جدول ۳ توضیح داده شده است.

جدول ۲. آیکون ها

جدول ۳. انواع عملکرد

جدول ۴. کدهای رنگ led

جدول ۵. کدهای framework

عیب‌یابی

400 (Bad request)

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

Authentication credentials were not provided

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

Header:
   "Authorization": "Token $TOKEN"

توکن بعد از کلمه‌ی توکن با یک فاصله قرار میگیرد. (بجای $TOKEN توکن خود را قرار دهید)