คู่มือการผสานรวม Unity SDK เบื้องต้น

คู่มือนี้จะแนะนำขั้นตอนการผสานรวม Pushwoosh Unity SDK เข้ากับแอปพลิเคชันของคุณ

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

บัญชี Pushwoosh
โปรเจกต์ Pushwoosh ที่ตั้งค่าไว้ในบัญชีของคุณ
Unity 2021.3 หรือใหม่กว่า
สำหรับ iOS:
- แพลตฟอร์ม iOS ที่กำหนดค่าเพื่อส่ง push notifications เราแนะนำให้ใช้ Token-Based Authentication ซึ่งเป็นวิธีที่ง่ายที่สุด
- ตั้งค่า Gateway เป็น Sandbox เพื่อส่ง push ไปยัง simulator
- หากต้องการรับ iOS SDK แบบเนทีฟผ่าน Swift Package Manager: ต้องใช้ Unity 2021.3.15 ขึ้นไป ตั้งค่า Target minimum iOS Version เป็น 15.0 ขึ้นไป และเข้าถึง github.com ได้ขณะที่ Xcode บิลด์โปรเจกต์ หากใช้ Unity 2021.3.0–2021.3.14 หรือ iOS target ที่ต่ำกว่า SDK จะถูกเพิ่มผ่าน CocoaPods (ดู เลือกวิธีเพิ่ม iOS SDK)
สำหรับ 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 Unity SDK

เพิ่มข้อมูลต่อไปนี้ลงใน Packages/manifest.json ของคุณ:

{
  "dependencies": {
    "com.pushwoosh.unity.core": "6.3.0",
    "com.pushwoosh.unity.android": "6.3.0",
    "com.pushwoosh.unity.ios": "6.3.0"
  },
  "scopedRegistries": [
    {
      "name": "npmjs",
      "url": "https://registry.npmjs.org",
      "scopes": ["com.pushwoosh"]
    }
  ]
}

เพิ่มเฉพาะแพ็คเกจแพลตฟอร์มที่คุณต้องการ ตัวอย่างเช่น ละเว้น com.pushwoosh.unity.android หากคุณกำหนดเป้าหมายเป็น iOS เท่านั้น

ใน Unity ไปที่ Window > Package Manager > + > Add package from git URL และเพิ่ม URL ต่อไปนี้ทีละรายการ:

https://github.com/Pushwoosh/pushwoosh-unity.git?path=com.pushwoosh.unity.core
https://github.com/Pushwoosh/pushwoosh-unity.git?path=com.pushwoosh.unity.android
https://github.com/Pushwoosh/pushwoosh-unity.git?path=com.pushwoosh.unity.ios

ดาวน์โหลด Pushwoosh.unitypackage จาก GitHub Releases และนำเข้าผ่าน Assets > Import Package > Custom Package

2. ติดตั้ง External Dependency Manager

ส่วน Android ของ SDK จำเป็นต้องใช้ External Dependency Manager for Unity (EDM4U) เพื่อจัดการ dependencies แบบเนทีฟของ Android ข้ามขั้นตอนนี้หากคุณพัฒนาสำหรับ iOS เท่านั้น

เพิ่ม scoped registry ต่อไปนี้ลงใน Packages/manifest.json ของคุณ:

{
  "scopedRegistries": [
    {
      "name": "package.openupm.com",
      "url": "https://package.openupm.com",
      "scopes": ["com.google.external-dependency-manager"]
    }
  ]
}

จากนั้นเพิ่มแพ็คเกจไปยัง dependencies ของคุณ:

"com.google.external-dependency-manager": "1.2.183"

3. เลือกวิธีเพิ่ม iOS SDK

โดยค่าเริ่มต้น การ export สำหรับ iOS จะดึง SDK แบบเนทีฟจาก Swift package Pushwoosh-XCFramework ผ่าน Swift Package Manager คุณไม่จำเป็นต้องใช้ CocoaPods หรือ EDM4U สำหรับ iOS และไม่ต้องรัน pod install

หากต้องการเปลี่ยนแหล่งที่มาของ iOS SDK หรือเพิ่มโมดูลเสริม ให้เปิด Window > Pushwoosh SDK Setup ใน Unity Editor:

ใน iOS SDK from ให้เลือก Swift Package Manager หรือ CocoaPods
เมื่อใช้ Swift Package Manager ให้เลือกโมดูลเสริมที่แอปของคุณใช้ใต้ Modules (Swift Package Manager only): PushwooshLiveActivities, PushwooshInboxKit, PushwooshInApp, PushwooshVoIP, PushwooshForegroundPush, PushwooshKeychain, PushwooshGRPC, PushwooshGeozones โมดูลจะถูกลิงก์กับ target ของแอป หากต้องการใช้โมดูลใน app extension ของคุณเอง ให้เพิ่มโมดูลนั้นใน target ของ extension ใน Xcode เมื่อใช้ CocoaPods การ export จะไม่มีโมดูลเหล่านี้

การ export จะกลับไปใช้ CocoaPods และคอนโซลของ Unity จะแจ้งเหตุผล เมื่อเข้าเงื่อนไขข้อใดข้อหนึ่งต่อไปนี้:

เลือก CocoaPods ไว้ใน Window > Pushwoosh SDK Setup
โปรเจกต์มี pod PushwooshXCFramework อยู่แล้ว ในไฟล์ *Dependencies.xml ที่ EDM4U อ่าน หรือใน Podfile หากต้องการเปลี่ยนไปใช้ Swift Package Manager ให้ลบ pod นั้นออก สำหรับ Geozones ให้ลบ pod PushwooshXCFramework/Geozones และเลือก PushwooshGeozones ใน Window > Pushwoosh SDK Setup
เวอร์ชันของ Unity เก่ากว่า 2021.3.15
Target minimum iOS Version ต่ำกว่า 15.0

เมื่อใช้ CocoaPods ไม่จำเป็นต้องใช้ EDM4U โดย SDK จะรัน pod install หลังการ export และสร้าง Podfile เอง เว้นแต่มีการติดตั้ง EDM4U ซึ่งจะเขียน Podfile แทน หาก pod install ล้มเหลว คอนโซลของ Unity จะแสดงข้อผิดพลาด ให้รัน pod install ในโฟลเดอร์ของโปรเจกต์ Xcode ที่ export แล้ว

หากสภาพแวดล้อมการบิลด์ของคุณเข้าถึง github.com ไม่ได้ Xcode จะไม่สามารถ resolve Swift package ได้ ให้เลือก CocoaPods ใน Window > Pushwoosh SDK Setup สำหรับการบิลด์ลักษณะนี้

การ export ผ่าน Swift Package Manager จะคง Unity-iPhone.xcworkspace ไว้ ดังนั้นสคริปต์บิลด์และ CI ที่บิลด์ workspace จะทำงานได้โดยไม่ต้องเปลี่ยนแปลง

เมื่อคุณอัปเดตเป็นเวอร์ชัน 6.3.0 ขึ้นไป โปรเจกต์ที่เคยได้รับ iOS SDK ผ่าน CocoaPods หรือ EDM4U จะเปลี่ยนไปใช้ Swift Package Manager เว้นแต่มีเงื่อนไขข้อใดข้อหนึ่งข้างต้นที่ทำให้ยังคงใช้ CocoaPods

หากต้องการใช้ CocoaPods ต่อ ให้เลือกใน Window > Pushwoosh SDK Setup
หากคุณ export ผ่าน Swift Package Manager ลงในโฟลเดอร์ของการ export ด้วย CocoaPods ครั้งก่อน pod ของ Pushwoosh จะถูกลบออกจาก Podfile แต่โปรเจกต์ Xcode ยังคงอ้างอิงถึง Pods และบิลด์ได้จาก Unity-iPhone.xcworkspace เท่านั้น ให้บิลด์ workspace หรือ export ลงในโฟลเดอร์ใหม่เพื่อให้ได้โปรเจกต์ที่ไม่มี CocoaPods

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

สร้างสคริปต์ PushNotificator.cs และแนบไปกับ GameObject ใดก็ได้ใน scene:

using UnityEngine;
using System.Collections.Generic;

public class PushNotificator : MonoBehaviour
{
    void Start()
    {
        Pushwoosh.ApplicationCode = "XXXXX-XXXXX";
        Pushwoosh.FcmProjectNumber = "XXXXXXXXXXXX";

        Pushwoosh.Instance.OnRegisteredForPushNotifications += (token) => {
            Debug.Log("Push token: " + token);
        };

        Pushwoosh.Instance.OnFailedToRegisteredForPushNotifications += (error) => {
            Debug.Log("Registration failed: " + error);
        };

        Pushwoosh.Instance.RegisterForPushNotifications();
    }
}

แทนที่:

XXXXX-XXXXX ด้วย Pushwoosh Application Code ของคุณ
XXXXXXXXXXXX ด้วยหมายเลขโปรเจกต์ Firebase ของคุณ (สำหรับ Android เท่านั้น)

5. การตั้งค่าแบบเนทีฟสำหรับ iOS

5.1 Capabilities

หลังจาก build โปรเจกต์ iOS จาก Unity แล้ว ให้เปิดโปรเจกต์ Xcode ที่สร้างขึ้นและเพิ่ม capabilities ต่อไปนี้ใน Signing & Capabilities:

Push Notifications
Background Modes โดยเลือก Remote notifications

สำหรับ Time Sensitive Notifications (iOS 15+) ให้เพิ่ม capability Time Sensitive Notifications ด้วย

5.2 Info.plist

เพิ่ม Pushwoosh Device API Token ไปยัง Info.plist ของคุณ:

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

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

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

ทำตาม คู่มือเนทีฟ เพื่อเพิ่ม extension target

6. การตั้งค่าแบบเนทีฟสำหรับ Android

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

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

6.2 เพิ่มข้อมูลเมตาของ Pushwoosh

เพิ่ม Pushwoosh Device API Token ไปยัง Assets/Plugins/Android/AndroidManifest.xml ของคุณภายในแท็ก <application>:

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

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

Build และรันโปรเจกต์บนแพลตฟอร์มเป้าหมายของคุณ
ให้สิทธิ์สำหรับ push notifications เมื่อมีข้อความแจ้ง
ไปที่ Pushwoosh Control Panel และ ส่ง push notification

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

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

ตัวดักจับ event ของ Push notification

SDK มีตัวดักจับ event สองตัวสำหรับจัดการ push notifications:

OnPushNotificationsReceived — ทำงานเมื่อมี push notification เข้ามา
OnPushNotificationsOpened — ทำงานเมื่อผู้ใช้แตะที่การแจ้งเตือน

ตั้งค่าตัวดักจับเหล่านี้ระหว่างการเริ่มต้น SDK:

void Start()
{
    Pushwoosh.ApplicationCode = "XXXXX-XXXXX";
    Pushwoosh.FcmProjectNumber = "XXXXXXXXXXXX";

    Pushwoosh.Instance.OnPushNotificationsReceived += (payload) => {
        Debug.Log("Push received: " + payload);
    };

    Pushwoosh.Instance.OnPushNotificationsOpened += (payload) => {
        Debug.Log("Push opened: " + payload);
    };

    Pushwoosh.Instance.RegisterForPushNotifications();
}

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

ปรับแต่ง push notifications ให้เป็นแบบส่วนตัวโดยการระบุผู้ใช้และตั้งค่าคุณสมบัติต่างๆ:

// ตั้งค่า User ID สำหรับการติดตามข้ามอุปกรณ์
Pushwoosh.Instance.SetUserId("user-123");

// ตั้งค่าอีเมลผู้ใช้
Pushwoosh.Instance.SetEmail("user@example.com");

// ตั้งค่าผู้ใช้ด้วย ID และอีเมล
Pushwoosh.Instance.SetUser("user-123", new List<string> { "user@example.com" });

// ตั้งค่าภาษาที่ต้องการ
Pushwoosh.Instance.SetLanguage("en");

Events

ติดตามการกระทำของผู้ใช้เพื่อวิเคราะห์พฤติกรรมและกระตุ้นการส่งข้อความอัตโนมัติ:

// ติดตาม event การล็อกอิน
Pushwoosh.Instance.PostEvent("login", new Dictionary<string, object> {
    { "username", "user-123" },
    { "login_type", "email" }
});

// ติดตาม event การซื้อ
Pushwoosh.Instance.PostEvent("purchase", new Dictionary<string, object> {
    { "product_id", "SKU-001" },
    { "price", 29.99 },
    { "currency", "USD" }
});

การตั้งค่าการสื่อสาร

อนุญาตให้ผู้ใช้เลือกรับหรือไม่รับ push notifications ผ่านโปรแกรมได้:

// เปิดใช้งานการสื่อสาร
Pushwoosh.Instance.SetCommunicationEnabled(true);

// ปิดใช้งานการสื่อสาร
Pushwoosh.Instance.SetCommunicationEnabled(false);

// ตรวจสอบสถานะปัจจุบัน
bool isEnabled = Pushwoosh.Instance.IsCommunicationEnabled();

การจัดการ Badge

ควบคุมหมายเลข badge ของแอปบนแพลตฟอร์มที่รองรับ:

// ตั้งค่า badge เป็นหมายเลขที่กำหนด
Pushwoosh.Instance.SetBadgeNumber(3);

// เพิ่มค่า badge
Pushwoosh.Instance.AddBadgeNumber(1);

// ล้างค่า badge
Pushwoosh.Instance.SetBadgeNumber(0);

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

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

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