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

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

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

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

ข้อกำหนด

• บัญชี Pushwoosh
• โปรเจกต์ Pushwoosh ที่ตั้งค่าไว้ในบัญชีของคุณ
• สำหรับการผสานรวม iOS:
  • แพลตฟอร์ม iOS ที่กำหนดค่าไว้เพื่อส่ง push notifications เราแนะนำให้ใช้ การกำหนดค่าการตรวจสอบสิทธิ์แบบ Token-Based เป็นแนวทางที่ง่ายที่สุด
  • ตั้งค่า Gateway เป็น Sandbox เพื่อส่ง pushes ไปยัง 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

เพิ่มแพ็กเกจ 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

ตรวจสอบอีกครั้งว่าแพ็กเกจติดตั้งถูกต้อง:

flutter pub deps | grep pushwoosh_flutter

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

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

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

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

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__ คือรหัสแอปพลิเคชันจาก Pushwoosh Control Panel
• __YOUR_FCM_SENDER_ID__ คือหมายเลขโปรเจกต์ Firebase จาก Firebase Console

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

3.1 ความสามารถ

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

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

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

หากคุณตั้งใจจะใช้ Time Sensitive Notifications (iOS 15+) ให้เพิ่มความสามารถ 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. การตั้งค่า Android Native

4.1 ติดตั้ง dependencies

ตรวจสอบให้แน่ใจว่า dependencies และ plugins ที่จำเป็นถูกเพิ่มลงใน Gradle scripts ของคุณแล้ว:

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

ในไฟล์ 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. Build และรันโปรเจกต์
2. ไปที่ Pushwoosh Control Panel และ ส่ง push notification
3. คุณควรเห็น notification ในแอป

การผสานรวมขั้นสูง

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

Push notification event listeners

ใน Pushwoosh SDK มี event listeners สองตัวที่ออกแบบมาสำหรับการจัดการ push notifications:

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

คุณควรตั้งค่า event listeners เหล่านี้ทันทีหลังจากเริ่มต้น 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 คือคู่คีย์-ค่าที่กำหนดให้กับผู้ใช้หรืออุปกรณ์ ซึ่งช่วยให้สามารถแบ่งกลุ่มตามคุณลักษณะต่างๆ เช่น ความชอบหรือพฤติกรรม ทำให้สามารถส่งข้อความแบบกำหนดเป้าหมายได้

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 { *; }

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

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