คู่มือการผสานการทำงานพื้นฐานของ Capacitor SDK

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

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

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

ข้อกำหนด

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

ขั้นตอนการผสานการทำงาน

1. เพิ่ม Dependency ของ Pushwoosh Capacitor SDK

เพิ่ม dependency ของ Pushwoosh Capacitor SDK ไปยังโปรเจกต์ของคุณ:

npm install pushwoosh-capacitor-plugin

ซิงค์การกำหนดค่า Capacitor:

npx cap sync

1.1 เลือก package manager สำหรับ iOS

npx cap sync จะติดตั้งส่วน iOS ของปลั๊กอินด้วย package manager ที่โปรเจกต์ Capacitor ของคุณใช้ ได้แก่ Swift Package Manager หรือ CocoaPods ทั้งสองแบบมาพร้อม Pushwoosh SDK แบบ native และ Inbox UI เวอร์ชันเดียวกัน Swift Package Manager รองรับใน Capacitor 7 และ Capacitor 8

โปรเจกต์ที่มีอยู่จะใช้ package manager เดิม: หากมี ios/App/CapApp-SPM อยู่ Capacitor CLI จะใช้ Swift Package Manager มิฉะนั้นจะใช้ CocoaPods สำหรับแพลตฟอร์ม iOS ใหม่:

Capacitor 8

Capacitor 8 สร้างโปรเจกต์ Swift Package Manager เป็นค่าเริ่มต้น:

npx cap add ios

หากต้องการใช้ CocoaPods แทน ให้รัน npx cap add ios --packagemanager CocoaPods

Capacitor 7

Capacitor 7 สร้างโปรเจกต์ CocoaPods เป็นค่าเริ่มต้น หากต้องการใช้ Swift Package Manager ให้รัน:

npx cap add ios --packagemanager SPM

คำสั่งจะสร้างโปรเจกต์ แล้วหยุดพร้อมข้อผิดพลาด ENOENT ... Podfile ขณะพยายามรัน pod install โปรเจกต์ถูกสร้างอย่างถูกต้องแล้ว ให้ตั้งค่าให้เสร็จด้วย:

npx cap sync ios

เมื่อใช้ Swift Package Manager, Capacitor CLI จะเพิ่มปลั๊กอินลงใน ios/App/CapApp-SPM และปลั๊กอินจะนำ Pushwoosh iOS SDK และ Inbox UI มาด้วย อย่าเพิ่ม Pushwoosh SDK ลงในแอปซ้ำอีกครั้ง ไม่ว่าจะเป็น pod หรือแพ็กเกจเวอร์ชันอื่น

การเลิกใช้ CocoaPods

CocoaPods trunk จะกลายเป็นแบบอ่านอย่างเดียวในวันที่ 2 ธันวาคม 2026 และ Pushwoosh กำลังย้าย iOS SDK ไปใช้ Swift Package Manager ปลั๊กอินที่เผยแพร่หลังวันดังกล่าวจะใช้เฉพาะ Swift package จนกว่าจะถึงวันนั้น pod install และการ build โปรเจกต์ CocoaPods ใน Xcode จะแสดงคำเตือนเกี่ยวกับเรื่องนี้ คำเตือนนี้ไม่ส่งผลต่อการ build

หากต้องการย้ายโปรเจกต์ CocoaPods ที่มีอยู่ ให้รัน npx cap spm-migration-assistant แล้วทำตามขั้นตอนแบบ manual ใน Xcode ที่คำสั่งลิงก์ไว้ คำสั่งนี้ต้องใช้ @capacitor/cli 7.4.0 ขึ้นไป

2. การเริ่มต้น Capacitor SDK

ในไฟล์ JavaScript หลักของคุณ ให้ import และเริ่มต้น Pushwoosh SDK:

index.js

import { Pushwoosh } from 'pushwoosh-capacitor-plugin';

// เริ่มต้น SDK
Pushwoosh.onDeviceReady({
    appid: "__YOUR_APP_CODE__"
});

// ลงทะเบียนสำหรับ push notifications
Pushwoosh.registerDevice()
    .then(result => {
        console.log("Push token:", result.pushToken);
        // จัดการการลงทะเบียนที่สำเร็จ
    })
    .catch(error => {
        console.error("Failed to register device:", error);
        // จัดการข้อผิดพลาดในการลงทะเบียน
    });

โดยที่:

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

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

3.1 Capabilities

เพื่อเปิดใช้งาน Push Notifications ในโปรเจกต์ของคุณ คุณต้องเพิ่ม capabilities บางอย่าง

ในส่วน Signing & Capabilities ให้เพิ่ม capabilities ต่อไปนี้:

• Push Notifications
• Background Modes หลังจากเพิ่ม capability นี้แล้ว ให้เลือกช่องสำหรับ Remote notifications

หากคุณต้องการใช้ Time Sensitive Notifications (iOS 15+) ให้เพิ่ม capability Time Sensitive Notifications ด้วย

3.2 Info.plist

ใน ios/App/App/Info.plist ของคุณ ให้ตั้งค่าคีย์ __PUSHWOOSH_DEVICE_API_TOKEN__ เป็น Pushwoosh Device API Token:

info.plist

<key>Pushwoosh_API_TOKEN</key>
<string>__PUSHWOOSH_DEVICE_API_TOKEN__</string>

3.3 การติดตามการส่งข้อความ

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

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

• CocoaPods: ทำตามขั้นตอน Dependencies สำหรับ Notification Service Extension (สำหรับ CocoaPods เท่านั้น) ในคู่มือ native ใน ios/App/Podfile ให้เพิ่ม pod 'PushwooshXCFramework' โดยไม่ระบุเวอร์ชันลงใน extension target เพื่อให้ได้เวอร์ชันเดียวกับที่ปลั๊กอินใช้ จากนั้นรัน npx cap sync ios

• Swift Package Manager: ข้ามขั้นตอน dependencies ของ CocoaPods ในคู่มือ native แล้วเพิ่ม SDK ลงใน extension target ใน Xcode ด้วยตนเอง เนื่องจาก target ไม่ได้สืบทอด dependencies ของปลั๊กอิน:

  1. เปิด extension target > General > Frameworks and Libraries
  2. เพิ่ม product PushwooshFramework จากแพ็กเกจ Pushwoosh-XCFramework โดยใช้เวอร์ชันที่มีอยู่แล้วใน Package.resolved

  หากคุณย้ายมาจาก CocoaPods ตรวจสอบให้แน่ใจว่า extension ไม่ได้รับ PushwooshXCFramework ในรูปแบบ pod อีกต่อไป เพื่อไม่ให้แอปมี SDK ซ้ำสองชุด

จากนั้น import PushwooshFramework ในโค้ดของ extension ส่วน App target ไม่ต้องทำอะไรเพิ่ม เนื่องจากได้รับ Pushwoosh SDK ผ่านปลั๊กอินแล้ว

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

4.1 ติดตั้ง dependencies

ตรวจสอบให้แน่ใจว่าได้เพิ่ม dependencies และ plugin ที่จำเป็นลงในสคริปต์ Gradle ของคุณแล้ว:

เพิ่ม Google Services Gradle plugin ไปยัง dependencies ของ build.gradle ระดับโปรเจกต์ของคุณ:

android/build.gradle

buildscript {
  dependencies {
    classpath 'com.google.gms:google-services:4.3.15'
  }
}

ใช้ plugin ในไฟล์ build.gradle ระดับแอปของคุณ:

app/build.gradle

apply plugin: 'com.google.gms.google-services'

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

วางไฟล์ google-services.json ลงในโฟลเดอร์ android/app ในไดเรกทอรีโปรเจกต์ของคุณ

4.3 เพิ่ม metadata ของ Pushwoosh

ใน main/AndroidManifest.xml ของคุณ ให้เพิ่ม Pushwoosh Device API Token ภายในแท็ก <application>:

AndroidManifest.xml

<meta-data android:name="com.pushwoosh.apitoken" android:value="__YOUR_DEVICE_API_TOKEN__" />

สำคัญ: ตรวจสอบให้แน่ใจว่าได้ให้สิทธิ์การเข้าถึงของ token กับแอปที่ถูกต้องใน Pushwoosh Control Panel ของคุณ เรียนรู้เพิ่มเติม

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

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

การผสานการทำงานเพิ่มเติม

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

Event listener สำหรับ push notification

ใน Pushwoosh Capacitor SDK มี callback method สองวิธีสำหรับจัดการ push notification:

• pushReceivedCallback จะถูกเรียกเมื่อได้รับ push notification
• pushOpenedCallback จะถูกเรียกเมื่อผู้ใช้เปิดการแจ้งเตือน

คุณควรตั้งค่า callback เหล่านี้ทันทีหลังจากการเริ่มต้น SDK:

index.js

import { Pushwoosh } from 'pushwoosh-capacitor-plugin';

// ตั้งค่า callback เมื่อได้รับ push
await Pushwoosh.pushReceivedCallback((notification, err) => {
    if (err) {
        console.error("Failed to process received notification:", err);
    } else {
        console.log("Push received:", JSON.stringify(notification));
        // จัดการการแจ้งเตือนที่ได้รับ
    }
});

// ตั้งค่า callback เมื่อเปิด push
await Pushwoosh.pushOpenedCallback((notification, err) => {
    if (err) {
        console.error("Failed to process opened notification:", err);
    } else {
        console.log("Push opened:", JSON.stringify(notification));
        // จัดการการแจ้งเตือนที่เปิด
    }
});

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

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

import { Pushwoosh } from 'pushwoosh-capacitor-plugin';

class Registration {
  async afterUserLogin(user) {

    // ตั้งค่า User ID
    Pushwoosh.setUserId(user.getId);

    // การตั้งค่าข้อมูลผู้ใช้เพิ่มเติมเป็น tag สำหรับ Pushwoosh
    await Pushwoosh.setTags({
      "age": user.getAge(),
      "name": user.getName(),
      "last_login": user.getLastLoginDate()
    });
  }
}

Tags

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

import { Pushwoosh } from 'pushwoosh-capacitor-plugin';

class UpdateUser {
 async afterUserUpdateProfile(user) {

    // ตั้งค่ารายการหมวดหมู่โปรด
    await Pushwoosh.setTags({
      "favorite_categories": user.getFavoriteCategoriesList()
    });

    // ตั้งค่าข้อมูลการชำระเงิน
    await Pushwoosh.setTags({
      "is_subscribed": user.isSubscribed(),
      "payment_status": user.getPaymentStatus(),
      "billing_address": user.getBillingAddress()
    });
  }
}

Events

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

import { Pushwoosh } from 'pushwoosh-capacitor-plugin';

class Registration {

  // ติดตาม event การเข้าสู่ระบบ
  afterUserLogin(user) {
    Pushwoosh.postEvent("login", {
      "name": user.getName(),
      "last_login": user.getLastLoginDate()
    });
  }

  // ติดตาม event การซื้อ
  afterUserPurchase(product) {
    Pushwoosh.postEvent("purchase", {
      "product_id": product.getId(),
      "product_name": product.getName(),
      "price": product.getPrice(),
      "quantity": product.getQuantity()
    });
  }
}

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

หาก push ไม่ถูกส่งถึง ให้ค้นหารหัสข้อผิดพลาดสำหรับแพลตฟอร์มของคุณใน ข้อผิดพลาดในการส่ง เพื่อดูว่ารหัสนั้นหมายถึงอะไรและวิธีแก้ไข

หากคุณพบปัญหาใดๆ ในระหว่างขั้นตอนการผสานการทำงาน โปรดอ้างอิงถึงส่วนการสนับสนุนและชุมชน