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

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

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

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

ข้อกำหนด

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

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

1. เพิ่ม Pushwoosh Flutter SDK Dependency

เพิ่ม 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

ในคอมโพเนนต์รากของไฟล์ main.dart ของคุณ:

• นำเข้า 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__",
    "sender_id": "__YOUR_FCM_SENDER_ID__"
  });
  Pushwoosh.getInstance.registerForPushNotifications();
}

โดยที่:

• __YOUR_APP_ID__ คือ application code จาก Pushwoosh Control Panel
• __YOUR_FCM_SENDER_ID__ คือ project number ของ Firebase จาก Firebase Console

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

ใน 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 การติดตามการส่งข้อความ

คุณต้องเพิ่ม Notification Service Extension target ไปยังโปรเจกต์ของคุณ ซึ่งจำเป็นสำหรับการติดตามการส่งที่แม่นยำและฟีเจอร์ต่างๆ เช่น 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 การติดตั้ง dependencies สำหรับโปรเจกต์ iOS Flutter

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

flutter run

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

pod install --repo-update

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 ของ Push notification

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

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

คุณควรตั้งค่าตัวดักฟัง event เหล่านี้ทันทีหลังจากการเริ่มต้น 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) {

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

    // Set user email
    Pushwoosh().setEmail(user.getEmail());

    // Register SMS number
    // The SMS and WhatsApp numbers must be in E.164 format (e.g., "+1234567890") and be valid
    Pushwoosh().registerSmsNumber(user.getSmsNumber());

    // Register WhatsApp number
    Pushwoosh().registerWhatsappNumber(user.getWhatsappNumber());

    // 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 'package:pushwoosh_flutter/pushwoosh_flutter.dart';

class UpdateUser {
  void afterUserUpdateProfile(User user) {

    // 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 'package:pushwoosh_flutter/pushwoosh_flutter.dart';

class Registration {

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

  void afterUserPurchase(Product product) {

  // Track purchase 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 ด้วยตนเองและเพิ่มกฎที่จำเป็น

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

build.gradle

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

            signingConfig signingConfigs.debug
        }
    }

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

proguard-rules.pro

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

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

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