คู่มือการผสานรวมพื้นฐาน Expo SDK

ส่วนนี้มีข้อมูลเกี่ยวกับวิธีการผสานรวม Pushwoosh Expo SDK เข้ากับแอปพลิเคชันของคุณ

ข้อกำหนดเบื้องต้น

ในการผสานรวม Pushwoosh Expo SDK เข้ากับแอปของคุณ คุณจะต้องมีสิ่งต่อไปนี้:

Requirements

• บัญชี Pushwoosh
• โปรเจกต์ Pushwoosh ที่ตั้งค่าในบัญชีของคุณ
• สำหรับการผสานรวม iOS:
  • แพลตฟอร์ม iOS ที่กำหนดค่าให้ส่ง push notification เราขอแนะนำให้ใช้ การกำหนดค่า Token-Based Authentication เป็นวิธีที่ง่ายที่สุด
  • ตั้งค่า Gateway เป็น Sandbox เพื่อส่ง push ไปยัง simulator
• สำหรับการผสานรวม Android:
  • แพลตฟอร์ม Android ที่กำหนดค่าแล้ว
  • ไฟล์ google-services.json และ package name จากโปรเจกต์ Firebase ของคุณ
  • โปรเจกต์ Firebase ที่เชื่อมต่อกับแอปพลิเคชัน Android ของคุณ ทำตาม คู่มือการตั้งค่า Firebase หากจำเป็น
• Pushwoosh Application Code และ Pushwoosh Device API Token ของคุณจาก Pushwoosh Control Panel สำหรับแอปพลิเคชันของคุณ

ขั้นตอนการผสานรวม

1. ติดตั้งปลั๊กอิน

ติดตั้งปลั๊กอิน Pushwoosh Expo โดยใช้ Expo CLI

expo install pushwoosh-expo-plugin

ติดตั้ง Pushwoosh React Native SDK

npm install pushwoosh-react-native-plugin --save

2. ตั้งค่าคุณสมบัติของปลั๊กอิน

เพิ่มปลั๊กอินไปที่ด้านหน้าของอาร์เรย์ปลั๊กอินพร้อมกับคุณสมบัติที่จำเป็น:

app.json/app.config.js

{
  "expo": {
    "plugins": [
      [
        "pushwoosh-expo-plugin",
        {
          "mode": "development",
          "ios": {
            "PW_API_TOKEN": "__YOUR_DEVICE_API_TOKEN__"
          },
          "android": {
            "apiToken": "__YOUR_DEVICE_API_TOKEN__"
          }
        }
      ]
    ]
  }
}

โดยที่:

• mode ใช้เพื่อกำหนดค่า APNs environment entitlement มีค่าที่เป็นไปได้คือ “Development” หรือ “production”
• PW_API_TOKEN, apiToken คือ Pushwoosh Device API Token ของคุณ

3. เริ่มต้นการทำงานของ Pushwoosh

ใน root component ของแอปพลิเคชันของคุณ:

• นำเข้าปลั๊กอิน pushwoosh-react-native-plugin
• เริ่มต้นการทำงานของ Pushwoosh SDK
• เรียกใช้ register() ในตรรกะการเริ่มต้นของคุณเพื่อลงทะเบียนสำหรับ push notification

index.tsx

import Pushwoosh from 'pushwoosh-react-native-plugin';

Pushwoosh.init({
    "pw_appid": "__YOUR_APP_ID__"
});

Pushwoosh.register();

โดยที่:

• __YOUR_APP_ID__ คือ application code จาก Pushwoosh Control Panel

4. การตั้งค่า Native ของ Android

เพิ่มไฟล์การกำหนดค่า Firebase:

1. คัดลอกไฟล์ google-services.json ของคุณไปยังไดเรกทอรีรากของโปรเจกต์
2. ตั้งค่าคุณสมบัติ googleServicesFile เป็นพาธของ google-services.json ของคุณและระบุคุณสมบัติ package:

app.json/app.config.js

  "expo": {
    "name": "sample",
  "android": {
    "package": "com.pushwoosh.sample",
    "googleServicesFile": "./google-services.json"
  },
  "plugins": [
    [
      "pushwoosh-expo-plugin",
      {
        "mode": "development",
        "ios": {
          "PW_API_TOKEN": "__YOUR_DEVICE_API_TOKEN__"
        },
        "android": {
          "apiToken": "__YOUR_DEVICE_API_TOKEN__"
        }
      }
    ]
  ]
}

5. การตั้งค่า Native ของ iOS

ตั้งค่าคุณสมบัติ bundleIdentifier ให้กับอ็อบเจกต์ ios:

app.json/app.config.js

  "expo": {
    "name": "sample",
    "ios": {
      "bundleIdentifier": "com.pushwoosh.sample"
    },
    "plugins": [
    [
      "pushwoosh-expo-plugin",
      {
        "mode": "development",
        "ios": {
          "PW_API_TOKEN": "__YOUR_DEVICE_API_TOKEN__"
        },
        "android": {
          "apiToken": "__YOUR_DEVICE_API_TOKEN__"
        }
      }
    ]
  ]
}

6. Prebuild แอป

สร้างโค้ด native และกำหนดค่า dependency สำหรับแต่ละแพลตฟอร์มโดยการรัน prebuild:

npx expo prebuild

7. รันโปรเจกต์

1. บิลด์และรันโปรเจกต์:

Android

npx expo run:android

iOS

npx expo run:ios

2. ไปที่ Pushwoosh Control Panel และ ส่ง push notification
3. คุณควรเห็นการแจ้งเตือนในแอป

การผสานรวมเพิ่มเติม

ในขั้นตอนนี้ คุณได้ผสานรวม SDK และสามารถส่งและรับ push notification ได้แล้ว ตอนนี้เรามาสำรวจฟังก์ชันหลักกัน

Event listener สำหรับ Push notification

ใน Pushwoosh SDK มี event listener สองตัวที่ออกแบบมาเพื่อจัดการ push notification:

• onPushReceived event จะถูกทริกเกอร์เมื่อได้รับ push notification
• onPushAccepted event จะถูกทริกเกอร์เมื่อผู้ใช้เปิดการแจ้งเตือน

คุณควรตั้งค่า event listener เหล่านี้ทันทีหลังจากการเริ่มต้น SDK เมื่อแอปพลิเคชันเริ่มทำงาน:

import { DeviceEventEmitter } from 'react-native';
import Pushwoosh from 'pushwoosh-react-native-plugin';

class PushwooshNotificationHandler {
  setupPushListeners(): void {

    DeviceEventEmitter.addListener("pushReceived", (e) => {
      console.warn("Push received: " + JSON.stringify(e));
    });

    DeviceEventEmitter.addListener("pushOpened", (e) => {
      console.warn("Push opened:" + JSON.stringify(e));
    });

  }
}

การกำหนดค่าผู้ใช้

โดยการมุ่งเน้นไปที่พฤติกรรมและความชอบของผู้ใช้แต่ละคน คุณสามารถส่งมอบเนื้อหาที่ปรับให้เป็นส่วนตัว ซึ่งนำไปสู่ความพึงพอใจและความภักดีของผู้ใช้ที่เพิ่มขึ้น

import Pushwoosh from 'pushwoosh-react-native-plugin';

class Registration {
  afterUserLogin(user: User): void {

    // Set user ID
    Pushwoosh.setUserId(user.getId());

    // Set user email
    Pushwoosh.setEmails(user.getEmailList());

    // Setting additional user information as tags for Pushwoosh
    Pushwoosh.setTags({
      "age": user.getAge(),
      "name": user.getName(),
      "last_login": user.getLastLoginDate()
    });
  }
}

Tags

Tags คือคู่ของ key-value ที่กำหนดให้กับผู้ใช้หรืออุปกรณ์ ช่วยให้สามารถแบ่งกลุ่มตามคุณลักษณะต่างๆ เช่น ความชอบหรือพฤติกรรม ทำให้สามารถส่งข้อความที่ตรงเป้าหมายได้

import Pushwoosh from 'pushwoosh-react-native-plugin';

class UpdateUser {
  afterUserUpdateProfile(user: User): void {

    // Set list of favorite categories
    Pushwoosh.setTags({
      "favorite_categories": user.getFavoriteCategoriesList()
    });

    // Set payment information
    Pushwoosh.setTags({
      "is_subscribed": user.isSubscribed(),
      "payment_status": user.getPaymentStatus(),
      "billing_address": user.getBillingAddress()
    });
  }
}

Events

Events คือการกระทำหรือเหตุการณ์ที่เกิดขึ้นโดยผู้ใช้ภายในแอป ซึ่งสามารถติดตามเพื่อวิเคราะห์พฤติกรรมและทริกเกอร์ข้อความหรือการกระทำที่สอดคล้องกัน

import Pushwoosh from 'pushwoosh-react-native-plugin';

class Registration {

  // Track login event
  afterUserLogin(user: User): void {
    Pushwoosh.postEvent("login", {
      "name": user.getName(),
      "last_login": user.getLastLoginDate()
    });
  }

  // Track purchase event
  afterUserPurchase(product: Product): void {
    Pushwoosh.postEvent("purchase", {
      "product_id": product.getId(),
      "product_name": product.getName(),
      "price": product.getPrice(),
      "quantity": product.getQuantity()
    });
  }
}

การติดตามการส่งข้อความสำหรับ iOS

คุณต้องเพิ่ม Notification Service Extension target ไปยังโปรเจกต์ของคุณ นี่เป็นสิ่งจำเป็นสำหรับการติดตามการส่งที่แม่นยำและฟีเจอร์ต่างๆ เช่น Rich Media บน iOS

ทำตาม ขั้นตอนในคู่มือ native เพื่อเพิ่ม extension target และโค้ด Pushwoosh ที่จำเป็นภายในนั้น

คุณสมบัติเพิ่มเติมของปลั๊กอิน

คุณสมบัติ	ค่าเริ่มต้น	คำอธิบาย
คุณสมบัติ iOS
Pushwoosh_LOG_LEVEL	INFO	ระดับการบันทึกสำหรับ iOS ค่าที่เป็นไปได้: NONE, ERROR, WARN, INFO, DEBUG, NOISE
คุณสมบัติ Android
logLevel	INFO	ระดับการบันทึกสำหรับ Android หนึ่งใน: NONE, ERROR, WARN, INFO, DEBUG, NOISE
multiNotificationMode	true	สามารถเปลี่ยนเป็น false ได้ในกรณีที่คุณต้องการแสดงเฉพาะการแจ้งเตือนล่าสุดสำหรับผู้ใช้
icon	-	พาธไปยังไอคอนการแจ้งเตือนที่กำหนดเองสำหรับ Android

การแก้ไขปัญหา

หากคุณพบปัญหาใดๆ ในระหว่างกระบวนการผสานรวม โปรดดูที่ส่วน การสนับสนุนและชุมชน

FCM registration error: Failed to retrieve token. Is firebase configured correctly?

ตรวจสอบให้แน่ใจว่าคุณสมบัติ googleServicesFile ของ Firebase ของคุณได้รับการตั้งค่าในไฟล์การกำหนดค่า Expo และไฟล์ google-services.json ถูกเพิ่มไปยังไดเรกทอรีรากของโปรเจกต์ของคุณ:

app.json/app.config.js

"expo": {
  "name": "sample",
  "android": {
    "package": "com.pushwoosh.sample",
    "googleServicesFile": "./google-services.json"
  },
  "plugins": [
    [
      "pushwoosh-expo-plugin",
      {
        "mode": "development",
        "ios": {
          "PW_API_TOKEN": "__YOUR_DEVICE_API_TOKEN__"
        },
        "android": {
          "apiToken": "__YOUR_DEVICE_API_TOKEN__"
        }
      }
    ]
  ]
}

TypeError: Cannot read property ‘init’ of null

คุณอาจพบข้อผิดพลาดนี้เมื่อพยายามรันแอปบนอุปกรณ์
เพื่อแก้ไขปัญหานี้ ตรวจสอบให้แน่ใจว่าคุณได้ทำขั้นตอน prebuild เสร็จสิ้นแล้ว ซึ่งจะสร้างโค้ด native และกำหนดค่า dependency สำหรับแต่ละแพลตฟอร์ม

npx expo prebuild