راهنمای استفاده

انتخاب نسخه

React Native

راه‌اندازی

اضافه کردن کتابخانه react native

با استفاده از دستور زیر کتابخانه ی پوش‌پل را به پروژه خود اضافه کنید.

npm i -P pushpole-react-native

یا با استفاده از yarn :

yarn add pushpole-react-native

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

تغییرات AndroidManifest.xml

وارد پنل کاربری پوش‌پل شوید و در قسمت اپلیکیشن ها، روی آیکون دریافت منیفست بزنید (این آیکون را با کلیک بر روی علامت سه نقطه ی گوشه ی کارت اپلیکیشن می توانید ببینید).
منیفست ری‌اکت نیتیو را انتخاب کنید و محتویات آن را که مشابه کد زیر می باشد کپی کرده و به AndroidManifest.xml پروژه خود و زیر مجموعه تگ application اضافه کنید.

<meta-data android:name="com.pushpole.sdk.token" android:value="PUSHPOLE_TOKEN"/>

فایل مانیفست برنامه در آدرس زیر در پروژه قابل دسترسی‌ست:

android/src/main/AndroidManifest.xml

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

در صورتی که در اپلیکیشن خود از کتابخانه react-native-firebase استفاده می‌کنید، مراحل زیر را نیز طی کنید:

اگر در حین راه‌اندازی این کتابخانه سرویس زیر را به فایل منیفست اضافه کرده‌اید آن را حذف کنید:

<service android:name="io.invertase.firebase.messaging.RNFirebaseMessagingService">
  <intent-filter>
    <action android:name="com.google.firebase.MESSAGING_EVENT" />
  </intent-filter>
</service>

عبارت‌های زیر را به فایل منیفست پروژه اضافه کنید:

<service
    android:name="com.pushpole.sdk.fcm.FcmService"
    tools:node="remove" />

<service android:name="com.reactlibrary.RNPushPoleNotificationService">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
</service>

در صورتی که مقدار زیر در پارامتر‌های تگ manifest در فایل منیفست پروژه وجود ندارد، آن را اضافه کنید:

xmlns:tools="http://schemas.android.com/tools"

تغییرات app.js

در کامپوننت App.js و یا اولین کامپوننت‌ی که برنامه از آن جا شروع میشود کتابخانه پوش‌پل را اضافه کنید:

در صورتی که کامپوننت شما از نوع class می باشد در ‍constructor کد زیر را قرار دهید:

import React from "react";
import PushPole from "pushpole-react-native"; // * Import PushPole

class App extends React.Component {
    constructor(props) {
        super(props);
        // Initialize PushPole library
        PushPole.initialize(true);
    }

    render() {
        return (
            ...
        );
    }
}

و در صورتی که کامپوننت شما از نوع function می‌باشد می توانید به شکل زیر تابع initialize پوش‌پل را صدا بزنید:

import React, {useEffect} from "react";
import PushPole from "pushpole-react-native"; // * Import PushPole

const App = () => {
    // Use react hooks to initialize PushPole
    useEffect(() => {
        PushPole.initialize(true);
    }, []);


    return (
        ...
    );
}

صدا زدن تابع PushPole.init در قسمت هایی که در بالا گفته شده اجباری نمی باشد و می توانید در هر قسمت دیگری که تمایل داشتید این کد را صدا بزنید ولی با توجه به ساختار ری‌اکت توصیه می شود که این کد در اولین کامپوننت‌ی که کل اپلیکیشن از آن شروع می شود قرار داده شود.
اگر در تابع بالا مقدار true گذاشته شود و دستگاه کاربر شما گوگل پلی سرویس نداشته باشد و یا آن را غیرفعال کرده باشد دیالوگی باز می شود و به کاربر پیشنهاد نصب گوگل پلی سرویس داده می شود تا قابلیت دریافت و ارسال پوش نوتیفیکیشن فعال شود. اگر در تابع بالا false را قرار دهید، این دیالوگ برای کاربر باز نمی شود.

تست

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

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

توصیه می شود اپلیکیشن را بر روی موبایل یا تبلت اجرا و تست کنید. اگر می خواهید اپلیکیشن را بر روی Emulator تست کنید، بر روی ایمولاتور شما باید Google API نصب باشد.

امکانات

PushPoleId

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

PushPole.getId((pushpoleId) => 
    let pushpoleID = pushpoleId;
)};

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

PushPole.subscribe("sport");

برای لغو عضویت از این تاپیک از دستور زیر استفاده کنید:

PushPole.unsubscribe("sport");

توجه داشته باشید که توابع مربوط به عضو شدن و لغو عضویت در تاپیک باید بعد از پایان PushPole.initialize اجرا شوند. بنابراین آنها را بلافاصله بعد از PushPole.initialize قرار ندهید.

غیرفعال کردن نمایش پوش

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

PushPole.setNotificationOff();

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

PushPole.setNotificationOn();

ارسال پوش از یک دستگاه به دستگاه دیگر

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

PushPole.getId((pushpoleId) => 
    let pid=pushpoleId;
)};

به این روش pid هر دستگاه را می توانید بدست بیاورید و آن‌ها را در سرور خود ذخیره کنید تا برای ارسال اعلان به دستگاه از آن استفاده کنید.

برای ارسال اعلان ساده از دستور زیر استفاده کنید:

PushPole.sendSimpleNotifToUser("pid_a0e3-82ac-a0", "title", "content");

پارمتر اول pushpoleId است و پارامتر دوم و سوم به ترتیب تیتر و متن اعلان هستند.
برای ارسال اعلان پیشرفته از این دستور استفاده کنید:

PushPole.sendAdvancedNotifToUser("pid_a0e3-82ac-a0", "{ 'title':'تست', 'content':'پیام ارسالی از یک دستگاه ' }");

پارمتر اول pushpoleId است و پارامتر دوم یک رشته با فرمت JSON هست که مشخصات اعلان پیشرفته را تعیین می کند.

نمونه‌ی یک جیسون کامل برای ارسال:

{
  "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.pushpole.co/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:a_number",
        "action_type": "U"
      }
    }
  ]
}

برای ارسال JSON دلخواه از دستور زیر استفاده کنید:

PushPole.sendCustomJsonToUser("pid_a0e3-82ac-a0", "{ 'key1':'value1', 'key2':'value2' }");

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

اطلاع از رویداد‌های نوتیفیکیشن

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

دریافت نوتیفیکیشن
دریافت JSON (Custom content)
کاربر بر روی اعلان کلیک کند
کاربر اعلان را رد کند
کاربر بر روی دکمه‌ای از اعلان کلیک کند

نحوه کارکردن رویدادهای اعلان در ری‌اکت‌نیتیو

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

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

و برای حالتی که اپلیکیشن در بک‌گراند می‌باشد باید یک فایل جاوااسکریپ که در ادامه راهنما توضیج داده شده بسازید و event handler های مربوطه را در این فایل قرار دهید و نکته ای که اینجا قابل تامل می‌باشد این است که در حالت بک‌گراند شما در واقع در یک فایل مجزا از کامپوننت های ری‌اکت‌تان این رویداد ها را دریافت می‌کنید.

اپ باز باشد:

در این حالت در یکی از کامپوننت های اپلیکیشن‌تان (ترجیحا در بالای شاخه کامپوننت‌ها) کد زیر را در componentDidMount یا با استفاده از هوک در useEffect مطابق کد زیر قرار دهید

دقت کنید که در صورت استفاده از هوک useEffect حتما از [] در هوک استفاده کنید که فقط یک‌بار کالبک‌های اعلان اضافه شوند

import React, {useEffect} from "react";
import PushPole from "pushpole-react-native";

const App = () => {
    useEffect(() => {
        PushPole.addEventListener(PushPole.EVENTS.RECEIVED, (notification) => {
             // Notification was received
        });

        PushPole.addEventListener(PushPole.EVENTS.CLICKED, (notification) => {
             // Notification was clicked
        });

        PushPole.addEventListener(PushPole.EVENTS.DISMISSED, (notification) => {
             // Notification was dismissed
        });

        PushPole.addEventListener(PushPole.EVENTS.BUTTON_CLICKED, (notification) => {
             // Notification button was clicked
        });

        PushPole.addEventListener(PushPole.EVENTS.CUSTOM_CONTENT_RECEIVED, (notification) => {
             // Custom content was received
        });
    }, []); // Do not forget to use []

    return (
      // The jsx that would renders
    );  
}

اپ بسته باشد:

۱. ابتدا باید در فایل به آدرس ‍‍‍‍android/app/src/main/java/[your-app-package-name]/MainApplication.java که در داخل پروژه اپلیکیشن‌تان در زیر شاخه ‍‍‍android می‌باشد آن را پیدا کنید و در فایل ‍‍ MainApplication.java کد زیر را در متد onCreate قرار دهید:

com.pushpole.sdk.RNPushPoleNotificationListener.enableNotificationListener(this);

۲. کد زیر را در مانیفست اپلیکیشن و در داخل بلاک application که در آدرس زیر قابل دسترسی می‌باشد قرار دهید ‍‍‍‍android/app/src/main/AndroidManifest.xml

<service android:name="com.pushpole.sdk.service.RNPushPoleNotificationService" />

۳. در فایل ‍‍‍index.js پروژه که در روت پروژه‌تان می‌باشد کد زیر را قرار دهید:

AppRegistry.registerHeadlessTask('PushPoleNotificationTask', () => require('./notificationCallbacks'));

۴. سپس یک فایل در روت پروژه‌تان به نام notificationCallbacks.js بسازید (نام فایل بسیار مهم است و باید با نامی که در قسمت ۳ داده شده یکی باشد)

۵. در داخل فایل notificationCallbacks.js که در قسمت قبل ساخته اید کد زیر را قرار دهید:

import PushPole from "pushpole-react-native";

module.exports = async (notificationData) => {          
    if(notificationData['EVENT_TYPE'] === PushPole.EVENTS.RECEIVED) {
       // Notification received
    } else if (notificationData['EVENT_TYPE'] === PushPole.EVENTS.CLICKED) {
       // Notification clicked
    } else if (notificationData['EVENT_TYPE'] === PushPole.EVENTS.DISMISSED) {
       // Notification dismissed
    } else if (notificationData['EVENT_TYPE'] === PushPole.EVENTS.BUTTON_CLICKED) {
       // Notification Button clicked
    } else if (notificationData['EVENT_TYPE'] === PushPole.EVENTS.CUSTOM_CONTENT_RECEIVED) {
       // Custom Content Received
    }
};

نکته: دقت کنید که برای تست این حالت دوم یعنی زمانی که اپ در بک‌گراند می‌باشد باید از ابزار هایی نظیر logcat در اندروید استودیو و یا pidcat برای مشاهده لاگ و تست کردن استفاده کنید

حالت‌های مختلف رویداد در جدول زیر شرح‌ داده‌ شده‌است:

پارامتر ورودی	استفاده
`PushPole.EVENTS.RECEIVED`	زمانی که نوتیفیکیشن دریافت شد این متد اجرا می‌شود.
`PushPole.EVENTS.CLICKED`	زمانی که کاربر روی نوتیفیکیشن کلیک کند، این متد اجرا می‌شود
`PushPole.EVENTS.DISMISSED`	زمان که کاربر نوتیفیکیشن را رد کند، این متد اجرا می‌شود
`PushPole.EVENTS.BUTTON_CLICKED`	زمانی که کاربر روی یک دکمه‌ی نوتیفیکیشن کلیک‌کند، این متد اجرا می‌شود
`PushPole.EVENTS.CUSTOM_CONTENT_RECEIVED`	زمانی که نوتیفیکیشن همراه با جیسون دلخواه و یا جیسون دلخواه‌، دریافت شود این متد اجرا می‌شود

ایجاد و حذف کانال نوتیفیکیشن در اپلیکیشن (Android 8.0+ only)

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

PushPole.createNotificationChannel(
    "MY_CHANNEL_ID", //channelId
    "all news channel", //Channel Name
    "", //description about channel
    4, //importance: Number between 0 to 5 (5 is the most important)
    true, //enableLight
    true, //enableViberation
    true, //showBadge
    Color.BLUE, //led color
    [100, 200, 300, 400, 500, 400, 300, 200, 400] // Vibrate mode 
);

با استفاده از تابع زیر در برنامه خود می‌توانید کانال نوتیفیکشنی که قبلا ایجاد کردید را حذف کنید:

PushPole.removeNotificationChannel(
    "MY_CHANNEL_ID" //channelId
);

عیب یابی

کار نکردن دستور react-native link

در صورتی که با زدن کد زیر کتابخانه پوش‌پل به پروژه (اپلیکیشن) شما اضافه نشد یا خطایی مربوط به اضافه نشد کتابخانه پوش‌پل به اپلیکیشن تان را مشاهده کردید می توانید به صورت دستی تغییرات لازم را که در ادامه توضیح داده شده انجام دهید تا کتابخانه پوش‌پل را اضافه کنید.

react-native link pushpole-react-native

مراحل اضافه کردن دستی کتابخانه پوش‌پل

در فایل ‍build.gradle در آدرس android/app/build.gradle در یک خط مجزا در داخل dependencies مقدار زیر را اضافه کنید:

 implementation project(':pushpole-react-native')

در فایل MainApplication.java در آدرس android/app/src/main/java/پکیج نیم شما/MainApplication.java در ابتدای فایل مقدار زیر را قرار دهید:

import com.reactlibrary.RNPushPolePackage;

در همان فایل ‍‍MainApplication.java و در داخل متد Override شده getPackages مقدار new ReactNativePushPole() قرار دهید که خروجی آن مشابه کد زیر می شود:

@Override
protected List<ReactPackages> getPackages() {
    return Arrays.<ReactPackages>asList(
        new MainReactPackage(),
        new ReactNativePushPole()
    );
}

و در آخر در فایل settings.gradle در آدرس android/settings.gradle بعد از خط rootProject.name مقادیر زیر را قرار دهید:

include ':pushpole-react-native'
project(':pushpole-react-native').projectDir = new File(rootProject.projectDir, '../node_modules/pushpole-react-native/android')

شما می‌توانید خطاهای عمومی موجود در هنگام نصب در اندروید را در این لینک مشاهده نمایید.

style="display="none">

راهنمای استفاده

React Native

راه‌اندازی

اضافه کردن کتابخانه react native

تغییرات AndroidManifest.xml

تغییرات app.js

تست

توصیه می شود اپلیکیشن را بر روی موبایل یا تبلت اجرا و تست کنید. اگر می خواهید اپلیکیشن را بر روی Emulator تست کنید، بر روی ایمولاتور شما باید Google API نصب باشد.

امکانات

PushPoleId

تاپیک (topic)

غیرفعال کردن نمایش پوش

ارسال پوش از یک دستگاه به دستگاه دیگر

اطلاع از رویداد‌های نوتیفیکیشن

نحوه کارکردن رویدادهای اعلان در ری‌اکت‌نیتیو

ایجاد و حذف کانال نوتیفیکیشن در اپلیکیشن (Android 8.0+ only)

عیب یابی

کار نکردن دستور react-native link

مراحل اضافه کردن دستی کتابخانه پوش‌پل

لینک‌ها

سوالات متداول

مستندات

ارتباط با ما

سوالات متداول

مستندات