Unity SDK 기본 통합 가이드

이 가이드는 Pushwoosh Unity SDK를 애플리케이션에 통합하는 과정을 안내합니다.

전제 조건

Pushwoosh 계정.
계정에 설정된 Pushwoosh 프로젝트.
Unity 2021.3 이상.
iOS의 경우:
- 푸시 알림을 보내도록 구성된 iOS 플랫폼. 가장 간단한 접근 방식으로 토큰 기반 인증 사용을 권장합니다.
- 시뮬레이터에 푸시를 보내려면 게이트웨이를 Sandbox로 설정하세요.
- Swift Package Manager로 네이티브 iOS SDK를 가져오려면 Unity 2021.3.15 이상, 15.0 이상으로 설정된 Target minimum iOS Version, 그리고 Xcode가 프로젝트를 빌드할 때 github.com에 대한 접근이 필요합니다. Unity 2021.3.0–2021.3.14 또는 더 낮은 iOS 대상에서는 SDK가 CocoaPods로 추가됩니다(iOS SDK 추가 방법 선택 참조).
Android의 경우:
- 구성된 Android 플랫폼.
- Firebase 프로젝트의 project number(Sender ID라고도 함), google-services.json 파일 및 package name.
- Android 애플리케이션에 연결된 Firebase 프로젝트. 필요한 경우 Firebase 설정 가이드를 따르세요.
Pushwoosh 제어판의 Pushwoosh Application Code 및 Pushwoosh Device API Token.

통합 단계

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"]
    }
  ]
}

필요한 플랫폼 패키지만 추가하세요. 예를 들어, iOS만 타겟팅하는 경우 com.pushwoosh.unity.android를 생략하세요.

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

GitHub Releases에서 Pushwoosh.unitypackage를 다운로드하고 Assets > Import Package > Custom Package를 통해 가져오세요.

2. External Dependency Manager 설치

SDK의 Android 부분은 네이티브 Android 종속성을 해결하기 위해 External Dependency Manager for Unity (EDM4U)가 필요합니다. iOS만 대상으로 하는 경우 이 단계를 건너뛰세요.

Packages/manifest.json에 다음 scoped registry를 추가하세요:

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

그런 다음 종속성에 패키지를 추가하세요:

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

3. iOS SDK 추가 방법 선택

기본적으로 iOS 내보내기는 Swift Package Manager를 사용해 Swift 패키지 Pushwoosh-XCFramework에서 네이티브 SDK를 가져옵니다. iOS에는 CocoaPods나 EDM4U가 필요하지 않으며 pod install을 실행하지 않습니다.

iOS SDK의 소스를 변경하거나 선택적 모듈을 추가하려면 Unity Editor에서 Window > Pushwoosh SDK Setup을 엽니다:

iOS SDK from에서 Swift Package Manager 또는 CocoaPods를 선택합니다.
Swift Package Manager를 사용하는 경우 Modules (Swift Package Manager only) 아래에서 앱이 사용하는 선택적 모듈을 선택합니다: PushwooshLiveActivities, PushwooshInboxKit, PushwooshInApp, PushwooshVoIP, PushwooshForegroundPush, PushwooshKeychain, PushwooshGRPC, PushwooshGeozones. 모듈은 앱 타깃에 연결됩니다. 자체 앱 익스텐션에서 모듈을 사용하려면 Xcode에서 해당 모듈을 익스텐션 타깃에 추가하세요. CocoaPods를 사용하는 경우 이러한 모듈 없이 내보내집니다.

다음 중 하나라도 해당되면 내보내기는 CocoaPods로 대체되며, Unity 콘솔에 그 이유가 표시됩니다:

Window > Pushwoosh SDK Setup에서 CocoaPods가 선택되어 있습니다.
프로젝트에 이미 PushwooshXCFramework pod가 있습니다(EDM4U가 읽는 *Dependencies.xml 파일 또는 Podfile). Swift Package Manager로 전환하려면 해당 pod를 제거하세요. Geozones의 경우 PushwooshXCFramework/Geozones pod를 제거하고 Window > Pushwoosh SDK Setup에서 PushwooshGeozones를 선택하세요.
Unity 버전이 2021.3.15보다 이전입니다.
Target minimum iOS Version이 15.0 미만입니다.

CocoaPods를 사용하는 경우 EDM4U는 필요하지 않습니다. SDK는 내보내기 후 pod install을 실행하고 Podfile을 직접 생성합니다. 단, EDM4U가 설치되어 있으면 EDM4U가 대신 Podfile을 작성합니다. pod install이 실패하면 Unity 콘솔에 오류가 표시됩니다. 내보낸 Xcode 프로젝트 폴더에서 pod install을 실행하세요.

빌드 환경에서 github.com에 접근할 수 없으면 Xcode가 Swift 패키지를 해결할 수 없습니다. 이러한 빌드에는 Window > Pushwoosh SDK Setup에서 CocoaPods를 선택하세요.

Swift Package Manager 내보내기는 Unity-iPhone.xcworkspace를 유지하므로, 워크스페이스를 빌드하는 빌드 스크립트와 CI는 변경 없이 작동합니다.

4. SDK 초기화

PushNotificator.cs 스크립트를 생성하고 씬의 모든 GameObject에 연결하세요:

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

Unity에서 iOS 프로젝트를 빌드한 후, 생성된 Xcode 프로젝트를 열고 Signing & Capabilities에서 다음 capabilities를 추가하세요:

Push Notifications
Background Modes에서 Remote notifications 체크

Time Sensitive Notifications(iOS 15 이상)의 경우, Time Sensitive Notifications capability도 추가하세요.

5.2 Info.plist

Info.plist에 Pushwoosh Device API Token을 추가하세요:

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

5.3 메시지 전송 추적

Xcode 프로젝트에 Notification Service Extension 타겟을 추가하세요. 이는 iOS에서 정확한 전송 추적 및 Rich Media에 필요합니다.

네이티브 가이드에 따라 extension 타겟을 추가하세요.

6. Android 네이티브 설정

6.1 Firebase 구성 파일 추가

google-services.json 파일을 Unity 프로젝트의 Assets 디렉토리에 넣으세요.

6.2 Pushwoosh 메타데이터 추가

Assets/Plugins/Android/AndroidManifest.xml의 <application> 태그 내에 Pushwoosh Device API Token을 추가하세요:

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

7. 프로젝트 실행

대상 플랫폼에서 프로젝트를 빌드하고 실행하세요.
메시지가 표시되면 푸시 알림 권한을 부여하세요.
Pushwoosh 제어판으로 이동하여 푸시 알림을 보내세요.

확장된 통합

이 단계에서는 푸시 알림을 보내고 받을 수 있습니다. 아래 섹션에서는 핵심 SDK 기능에 대해 설명합니다.

푸시 알림 이벤트 리스너

SDK는 푸시 알림 처리를 위한 두 가지 이벤트 리스너를 제공합니다:

OnPushNotificationsReceived — 푸시 알림이 도착했을 때 트리거됩니다.
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();
}

사용자 구성

사용자를 식별하고 속성을 설정하여 푸시 알림을 개인화하세요:

// 교차 기기 추적을 위해 사용자 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");

// 문자열 태그
Pushwoosh.Instance.SetStringTag("favorite_category", "electronics");

// 정수 태그
Pushwoosh.Instance.SetIntTag("purchase_count", 5);

// 리스트 태그
Pushwoosh.Instance.SetListTag("interests", new List<object> { "sports", "music", "tech" });

// 모든 태그 가져오기
Pushwoosh.Instance.GetTags((tags, error) => {
    if (error != null) {
        Debug.Log("Error: " + error.Message);
        return;
    }
    foreach (var tag in tags) {
        Debug.Log(tag.Key + ": " + tag.Value);
    }
});

이벤트

사용자 행동을 추적하여 행동을 분석하고 자동화된 메시지를 트리거하세요:

// 로그인 이벤트 추적
Pushwoosh.Instance.PostEvent("login", new Dictionary<string, object> {
    { "username", "user-123" },
    { "login_type", "email" }
});

// 구매 이벤트 추적
Pushwoosh.Instance.PostEvent("purchase", new Dictionary<string, object> {
    { "product_id", "SKU-001" },
    { "price", 29.99 },
    { "currency", "USD" }
});

통신 환경설정

사용자가 프로그래밍 방식으로 푸시 알림을 수신하거나 거부하도록 허용하세요:

// 통신 활성화
Pushwoosh.Instance.SetCommunicationEnabled(true);

// 통신 비활성화
Pushwoosh.Instance.SetCommunicationEnabled(false);

// 현재 상태 확인
bool isEnabled = Pushwoosh.Instance.IsCommunicationEnabled();

배지 관리

지원되는 플랫폼에서 앱 배지 번호를 제어하세요:

// 배지를 특정 숫자로 설정
Pushwoosh.Instance.SetBadgeNumber(3);

// 배지 증가
Pushwoosh.Instance.AddBadgeNumber(1);

// 배지 지우기
Pushwoosh.Instance.SetBadgeNumber(0);

문제 해결

푸시가 전달되지 않으면 전송 오류에서 사용 중인 플랫폼의 오류 코드를 찾아 의미와 해결 방법을 확인하세요.

통합 과정에서 문제가 발생하면 지원 및 커뮤니티 섹션을 참조하세요.