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

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

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

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

ข้อกำหนด

• บัญชี 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. เพิ่ม Dependency ของ Pushwoosh Flutter SDK

เพิ่ม package pushwoosh_flutter ไปยังไฟล์ pubspec.yaml ของคุณ:

pubspec.yaml

dependencies:
  flutter:
    sdk: flutter
  # Use the latest version from https://pub.dev/packages/pushwoosh_flutter
  pushwoosh_flutter: ^[LATEST_VERSION]

ตรวจสอบ เวอร์ชันล่าสุด บน pub.dev

จากนั้น รันคำสั่งต่อไปนี้ในไดเรกทอรีรากของโปรเจกต์เพื่อติดตั้ง dependency:

flutter pub get

ตรวจสอบอีกครั้งว่า package ได้รับการติดตั้งอย่างถูกต้อง:

flutter pub deps | grep pushwoosh_flutter

# Example output:
# ❯ flutter pub deps | grep pushwoosh_flutter
# └── pushwoosh_flutter 2.3.11

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

ใน root component ของไฟล์ main.dart ของคุณ:

• Import package pushwoosh_flutter
• เริ่มต้น Pushwoosh SDK
• เรียกใช้ registerForPushNotifications() ในตรรกะการเริ่มต้นของคุณเพื่อลงทะเบียนสำหรับ push notification

main.dart

import 'package:pushwoosh_flutter/pushwoosh_flutter.dart';

void main() async {
  runApp(const MyApp());
  Pushwoosh.initialize({
    "app_id": "__YOUR_APP_ID__"
  });
  Pushwoosh.getInstance.registerForPushNotifications();
}

โดยที่:

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

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

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

ใน Runner/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 ที่จำเป็นภายในนั้น

เพื่อให้แน่ใจว่า Notification Service Extension ถูกผสานรวมในโปรเจกต์ Flutter ของคุณอย่างถูกต้อง คุณต้องใช้การกำหนดค่า Podfile ต่อไปนี้:

Podfile

target 'NotificationServiceExtension' do
  use_frameworks!
  use_modular_headers!

  pod 'PushwooshXCFramework'

  inherit! :search_paths
end

3.4 การติดตั้ง dependency สำหรับโปรเจกต์ iOS Flutter

ในการติดตั้ง dependency สำหรับโปรเจกต์ iOS Flutter ให้รันคำสั่งต่อไปนี้:

flutter run

หรือไปที่โฟลเดอร์ ios ใน terminal แล้วรัน:

pod install --repo-update

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

4.1 ติดตั้ง dependency

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

เพิ่ม Google Services Gradle plugin ไปยัง dependency ของ 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 SDK มี event listener สองตัวที่ออกแบบมาเพื่อจัดการ push notification:

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

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

import 'package:pushwoosh_flutter/pushwoosh_flutter.dart';

class PushwooshNotificationHandler {
  void setupPushListeners(Pushwoosh pushwoosh) {

    pushwoosh.onPushReceived.listen((event) {
      print("Push received: ${event.pushwooshMessage.payload}");
    });

    pushwoosh.onPushAccepted.listen((event) {
      print("Push accepted: ${event.pushwooshMessage.payload}");
    });

  }
}

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

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

import 'package:pushwoosh_flutter/pushwoosh_flutter.dart';

class Registration {
  void afterUserLogin(User user) {

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

    // ตั้งค่าอีเมลผู้ใช้
    Pushwoosh().setEmail(user.getEmail());

    // ลงทะเบียนหมายเลข SMS
    // หมายเลข SMS และ WhatsApp ต้องอยู่ในรูปแบบ E.164 (เช่น "+1234567890") และต้องถูกต้อง
    Pushwoosh().registerSmsNumber(user.getSmsNumber());

    // ลงทะเบียนหมายเลข WhatsApp
    Pushwoosh().registerWhatsappNumber(user.getWhatsappNumber());

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

Tags

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

import 'package:pushwoosh_flutter/pushwoosh_flutter.dart';

class UpdateUser {
  void afterUserUpdateProfile(User user) {

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

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

Events

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

import 'package:pushwoosh_flutter/pushwoosh_flutter.dart';

class Registration {

  // ติดตาม event การล็อกอิน
  void afterUserLogin(User user) {
    Pushwoosh().postEvent("login", {
      "name": user.getName(),
      "last_login": user.getLastLoginDate()
    });
  }

  void afterUserPurchase(Product product) {

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

การใช้ ProGuard

หมายเหตุ

โปรดทราบว่าคำสั่ง flutter build apk จะทำการ obfuscate โค้ดของคุณโดยค่าเริ่มต้น

ดังนั้น คุณอาจได้รับ exception นี้:

java.lang.IllegalStateException: Could not find class for name: com.pushwoosh.plugin.PushwooshNotificationServiceExtension

ในกรณีนี้มีสองวิธีแก้ไข:

1. ใช้คำสั่ง flutter build apk --no-shrink เพื่อคอมไพล์โค้ดของคุณโดยไม่มีการ obfuscation
2. หรือคุณสามารถเปิดใช้งาน ProGuard ด้วยตนเองและเพิ่ม rule ที่จำเป็น

ในการเปิดใช้งาน ProGuard สำหรับโปรเจกต์ของคุณ ให้เพิ่มสตริงต่อไปนี้ลงในไฟล์ build.gradle ของคุณ:

build.gradle

buildTypes {
        release {
            minifyEnabled true
            useProguard true
            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'

            signingConfig signingConfigs.debug
        }
    }

จากนั้น เพิ่ม rule ต่อไปนี้ไปยัง android/app/proguard-rules.pro

proguard-rules.pro

#Pushwoosh Flutter
-keep class com.pushwoosh.plugin.PushwooshPlugin { *; }
-keep class com.pushwoosh.plugin.PushwooshNotificationServiceExtension { *; }

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

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