REST API چشمک

نحوه استفاده

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

قبل از شروع به استفاده از API چشمک نیاز به دریافت API Key از پنل کاربری چشمک می باشد. به پنل خود وارد شده و از طریق منوی سمت راست روی تنظیمات کلیک کند. در جدول نمایش داده شده روی دکمه API Keys مربوط به اپلیکیشن انتخابی خود کلیک کنید. شما در این پنل می توانید با کلیک روی ساختن API با دسترسی کامل یک API Key تحویل بگیرید. در بالای جدول شناسه اپلیکیشن انتخابی شما وجود دارد. شما با داشتن شناسه اپلیکیشن و API Key مربوط به آن اپلیکیشن می توانید از API چشمک استفاده کنید.

_images/apiKeys.png

در تمامی درخواست های ارسالی به چشمک هدر های زیر به صورت الزامی باید وارد شوند:

header name value  
Content-Type application/json  
key {{APIKey}} API Key که در پنل چشمک دریافت کرده اید

پوش نوتیفیکیشن

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

ارسال پوش نوتیفیکیشن

آدرس ارسال پوش

POST https://api.cheshmak.me/v1/push/app/{{appId}}/send

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

Name Type Required Default description
afterOpenType String True   one of: openProgram,url,telegram
start Unix timestamp integer False Now زمان شروع ارسال
end Unix timestamp integer False ۲۴ ساعت پس از الآن زمان پایان ارسال: به شما کمک می کند تا مطمئن شوید پوش نوتیفیکیشن در خارج از بازه انتخابی شما ارسال نمی شود.
pushData.title String True   عنوان پوش، ماکزیمم کاراکتر: ۱۰۰
pushData.shortMessage String False   پیام کوتاه در پوش، ماکزیمم کاراکتر: ۱۰۰
pushData.icon String َURL | False |

آدرس آیکن در اینترنت |
pushData.customData Stringified json False ‘{}’ یک JSON که به صورت String در آمده است و به منظور ارسال داده به اپلیکیشن به کار می رود
pushData.url String url False   در صورت انتخاب url در afterOpenType به کار میرود
pushData.telegram String telegram url False   در صورت انتخاب telegram در afterOpenType به کار میرود

در زیر لیست پاسخ های برگشتی از سرور نمایش داده شده است:

در صورت موفقیت در عملیات :

statusCode: 200

مقدار دریافتی:

{
  “success”:true,
  “pushId": "ID"
}

در صورت خطا در ورود اطلاعات:

statusCode: 406

مقدار بازگشتی:

{
  success: false,
  error: 1, //invalid data
  message: “”
}

در صورت بروز خطا در وارد کردن AppKey:

statusCode: 403

مقدار بازگشتی:

{
  "success": false,
  "error": 2,
  "message": "invalid appId or api key"
}

در صورت بروز خطای داخلی در پردازش:

statusCode: 500

مقدار بازگشتی:

{
  success: false,
  error: 3, //internal error
  message: 'internal server error'
}

یک مثال از دستور CURL مربوطه به صورت زیر می باشد:

curl -X POST -H "Content-Type: application/json" -H "key: APIKEY" \
  -H "Cache-Control: no-cache" \
 -d '{
   "afterOpenType":"openProgram",
    "pushData":{
        "title":"this is some hi"
    }
}' "https://api.cheshmak.me/v1/push/app/57978086eeecf30b77359bb0/send"

مثالی از کد پی اچ پی برای ارسال پوش نوتیفیکیشن

<?php
$appId="APP ID";
$apiKey="YOUR API KEY";
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.cheshmak.me/v1/push/app/$appId/send",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\n   \"afterOpenType\":\"openProgram\",\n    \"pushData\":{\n        \"title\":\"this is some hi\"\n    }\n}",
  CURLOPT_HTTPHEADER => array(
    "cache-control: no-cache",
    "content-type: application/json",
    "key: $apiKey"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

دریافت لیست پوش های ارسال شده

GET: https://api.cheshmak.me/v1/push/app/[AppId]/list/[PAGENUM]

مقدار بازگشتی دارای ۲ فیلد است:

۱.succuss که یکی از مقادیر true یا false را دارد ۲.data که در صورت موفقیت دارای آرایه ای از آبجکت رکورد پوش می باشد.

دستور CURL مربوطه به صورت زیر است:

curl -X GET -H "key: APIKEY" \
-H "Cache-Control: no-cache" "https://api.cheshmak.me/v1/push/app/578099bb323840b01215e0dc/list"

مثالی از مقدار بازگشتی از این درخواست به صورت زیر می باشد:

{
  "success": true,
  "data": [
    {
      "_id": "5780b4bbe05669150200360d",
      "appId": "578099bb323840b01215e0dc",
      "__v": 0,
      "request": {
        "start": "2016-07-09T08:24:27.739Z",
        "end": "2016-07-10T08:24:27.739Z",
        "afterOpenType": "openProgram",
        "target": {
          "locationPolygons": [],
          "locationCircles": []
        },
        "pushData": {
          "title": "this is some hi",
          "shortMessage": "",
          "customData": "{}"
        }
      },
      "openedCount": 1,
      "deliveredCount": 1,
      "sentCount": 1,
      "status": "done"
    },
    {
      "_id": "5780b304323840b01215e0de",
      "appId": "578099bb323840b01215e0dc",
      "__v": 0,
      "request": {
        "start": "2016-07-09T08:17:08.088Z",
        "end": "2016-07-10T08:17:08.088Z",
        "afterOpenType": "openProgram",
        "target": {
          "locationPolygons": [],
          "locationCircles": []
        },
        "pushData": {
          "title": "تست پوش",
          "shortMessage": "متن پوش می باشد",
          "customData": "{}",
          "icon": "https://www.cheshmak.me/push-icons/5780b304323840b01215e0de.png",
          "url": "",
          "telegram": ""
        }
      },
      "openedCount": 1,
      "deliveredCount": 1,
      "sentCount": 1,
      "status": "done"
    }
  ]
}

دریافت وضعیت پوش ارسال شده

GET: https://api.cheshmak.me/v1/push/app/[AppId]/status/[PushId]
AppId: شناسه اپلیکیشن
PushId: شناسه پوش ارسال شده که پس از ارسال پوش دریافت کرده اید

این API همانند دریافت لیست پوش های ارسالی عمل می کند با این تفاوت که در فیلد data در خروجی به جای آرایه یک آبجکت از رکورد پوش تعیین شده می باشد.

مثالی از دستور CURL به صورت زیر می باشد:

curl -X GET \
-H "key: APIKEY" \
-H "Cache-Control: no-cache" "https://api.cheshmak.me/v1/push/app/578099bb323840b01215e0dc/status/5780b4bbe05669150200360d"

خروجی نمونه:

 {
  "success": true,
  "data": {
    "_id": "5780b4bbe05669150200360d",
    "appId": "578099bb323840b01215e0dc",
    "__v": 0,
    "request": {
      "start": "2016-07-09T08:24:27.739Z",
      "end": "2016-07-10T08:24:27.739Z",
      "afterOpenType": "openProgram",
      "target": {
        "locationPolygons": [],
        "locationCircles": []
      },
      "pushData": {
        "title": "this is some hi",
        "shortMessage": "",
        "customData": "{}"
      }
    },
    "openedCount": 1,
    "deliveredCount": 1,
    "sentCount": 1,
    "status": "done"
  }
}