푸시 알림 지원
푸시 알림을 통해 사용자 상호작용을 추적하여 리인게이지먼트 캠페인과 어트리뷰션 전환을 정확하게 측정할 수 있도록 Firebase 클라우드 메시징(FCM)을 Singular SDK와 연동하세요.
아래 구현 가이드라인에 따라 알림 데이터가 적절한 어트리뷰션을 위해 Singular SDK에 올바르게 전달되도록 하세요.
푸시 알림을 추적해야 하는 이유: 푸시 알림은 리인게이지먼트를 유도하지만 추적을 위해서는 올바른 연동이 필요합니다. Singular는 알림과 상호작용하는 사용자의 어트리뷰션을 올바르게 추적하여 마케팅 캠페인과 참여 전략을 최적화합니다.
구현 가이드
Singular SDK 연동
Singular Unity SDK 가이드에 설명된 표준 설치 지침에 따라 Unity 프로젝트에 Singular SDK를 연동하세요.
푸시 링크 경로 구성
푸시 알림 페이로드 구조 내에서 Singular 트래킹 링크가 위치한 JSON 경로를 정의합니다.
알림 데이터 구조에서 Singular 링크의 키 경로를 지정하는 슬래시로 구분된 문자열을 사용하여 푸시 링크 경로를 구성합니다.
// Configure push link paths in SDK initialization
SingularConfig config = new SingularConfig("SDK_KEY", "SDK_SECRET")
.WithPushNotificationsLinkPaths(new List<string>
{
"sng_link", // Top-level key
"path/to/url", // Nested path
"rootObj/nestedObj/singularLink" // Deep nested path
});
SingularSDK.InitializeSingularSDK();
경로 구성 예시:
-
단순 키: 페이로드의 최상위 키에
"sng_link"사용 -
중첩된 키: 중첩된 JSON 구조를 횡단하려면
"rootObj/nestedObj/key"을 사용합니다. - 다중 경로: 여러 경로 문자열을 정의하여 Singular 링크에 대해 가능한 여러 위치를 확인합니다.
참고: Unity 에디터는 인스펙터 UI를 통한 목록 입력을 지원하지 않으므로 경로는 중첩된 배열 대신 슬래시로 구분된 문자열로 구성됩니다.
플랫폼별 처리
iOS 푸시 알림 처리
종료 상태(앱이 실행되지 않음)
종료된 상태의 iOS 앱에는 수동 작업이 필요하지 않습니다. Singular iOS 연동은 SingularAppController 을 사용하여 푸시 추적을 자동으로 처리합니다.
자동 처리: 앱이 실행 중이 아닌 상태에서 사용자가 푸시 알림을 탭하면 앱이 실행되는 동안 Singular가 자동으로 알림 페이로드를 캡처합니다.
백그라운드 상태(백그라운드에서 앱 실행 중)
앱이 백그라운드 상태에서 알림을 수신하면 HandlePushNotification() 을 사용하여 푸시 데이터를 SDK로 전달합니다.
using UnityEngine;
using Singular;
using Firebase.Messaging;
using System.Collections.Generic;
public class PushNotificationHandler : MonoBehaviour
{
void Start()
{
// Subscribe to Firebase message received event
Firebase.Messaging.FirebaseMessaging.MessageReceived += OnMessageReceived;
}
private void OnMessageReceived(object sender, MessageReceivedEventArgs e)
{
Debug.Log("Received Firebase push notification");
// Extract notification data
var pushDataDictionary = new Dictionary<string, string>(e.Message.Data);
// Pass notification data to Singular SDK
SingularSDK.HandlePushNotification(pushDataDictionary);
// Your additional notification handling logic
DisplayNotification(e.Message);
}
}
중요: 사용자 지정 알림 처리 로직 전에 백그라운드 알림 핸들러 Script 내에서 HandlePushNotification()이 호출되는지 확인하세요.
안드로이드 푸시 알림 처리
자동 처리(권장)
백그라운드 및 종료 상태 모두에서 자동 푸시 알림 처리를 위해 메인 Unity 활동이 SingularUnityActivity을 확장하는지 확인하세요.
import com.singular.unitybridge.SingularUnityActivity;
public class MessagingUnityPlayerActivity extends SingularUnityActivity {
// Your custom activity logic here
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
// Your initialization code
}
}
모범 사례: SingularUnityActivity 을 확장하면 앱이 백그라운드 또는 종료 상태일 때 푸시 알림이 SDK에 의해 자동으로 처리되므로 수동 알림 처리가 필요하지 않습니다.
Firebase 연동 예제
사용자 지정 Firebase 메시지 처리 로직이 필요한 경우 리스너를 구현하고 알림 데이터를 Singular로 전달하세요.
using UnityEngine;
using Singular;
using Firebase.Messaging;
using System.Collections.Generic;
public class AndroidPushHandler : MonoBehaviour
{
void Start()
{
// Subscribe to Firebase messaging events
Firebase.Messaging.FirebaseMessaging.MessageReceived += OnMessageReceived;
Firebase.Messaging.FirebaseMessaging.TokenReceived += OnTokenReceived;
}
private void OnMessageReceived(object sender, MessageReceivedEventArgs e)
{
Debug.Log("Received a new Firebase message");
// Convert message data to dictionary
var pushDataDictionary = new Dictionary<string, string>(e.Message.Data);
// Forward to Singular SDK for attribution
SingularSDK.HandlePushNotification(pushDataDictionary);
// Your custom handling logic
ProcessNotificationContent(e.Message);
}
private void OnTokenReceived(object sender, TokenReceivedEventArgs token)
{
Debug.Log($"FCM Token received: {token.Token}");
// Store or use token as needed
// Note: Singular automatically handles token registration
}
private void ProcessNotificationContent(FirebaseMessage message)
{
// Your custom notification display or routing logic
string title = message.Notification?.Title ?? "Notification";
string body = message.Notification?.Body ?? "";
Debug.Log($"Notification: {title} - {body}");
}
}
유효성 검사 가이드
시작 세션에서 페이로드 확인
시작 세션 API 호출을 검사하여 푸시 알림 링크가 Singular에 올바르게 전달되었는지 확인합니다.
Singular SDK는 사용자가 알림을 탭할 때 시작 세션 요청의 singular_link 매개변수 아래에 푸시 알림 페이로드를 포함합니다.
세션 시작 요청 예시:
https://sdk-api-v1.singular.net/api/v1/start?
a=<SDK-Key>
&singular_link=https://singularassist2.sng.link/C4nw9/r1m0?_dl=singular%3A%2F%2Ftest&_smtype=3
&i=com.yourcompany.app
&s=1740905574084
&sdk=Singular/Unity-v1.0.0
대체 인증: Singular SDK 콘솔을 사용하여 푸시 알림 추적을 확인합니다. 딥링크 URL 필드를 확인하여 추적 링크가 올바르게 캡처되었는지 확인합니다.
고급 구성
ESP 도메인 구성
이메일 서비스 제공업체(ESP) 또는 기타 타사 도메인 내에 Singular 링크를 래핑하는 경우 외부 도메인을 구성합니다.
// Configure ESP domains for wrapped Singular links
SingularConfig config = new SingularConfig("SDK_KEY", "SDK_SECRET")
.WithESPDomains(new List<string> { "sl.esp.link", "custom.domain.com" });
SingularSDK.InitializeSingularSDK();
보안 참고: 기본적으로 Singular 링크 관리 페이지에 미리 정의된 sng.link도메인만 허용됩니다. 래핑된 링크를 사용하는 경우 ESP 도메인을 명시적으로 구성하세요.
동적 딥링크 라우팅
동적 리디렉션 재정의가 있는 하나의 Singular 추적 링크를 구성하여 Singular 알림에서 여러 개의 딥링크 대상을 구현하세요.
사용 사례 예시: 여러 가지 액션 옵션이 포함된 속보 알림
-
최신 뉴스 읽기:
newsapp://article?id=12345 -
인기 토픽:
newsapp://trending -
스포츠:
newsapp://sports
여러 개의 추적 링크를 만드는 대신 하나의 Singular 링크를 사용하고 사용자 선택에 따라 리디렉션을 동적으로 재정의하세요. 구현에 대한 자세한 내용은 Singular 추적 링크에서 리디렉션 재정의하기를 참조하세요.
중요 고려 사항
구현 참고 사항
-
콜백 핸들러 없음:
SetSingularLinkHandler과 달리 푸시 알림 기능은 페이로드 콜백을 제공하지 않습니다. 자체 딥링킹 로직을 구현하여 사용자를 앱 내의 특정 콘텐츠로 라우팅하세요. - 어트리뷰션 흐름: 사용자가 알림을 탭하면 Singular는 페이로드를 검색하여 SDK 초기화에 의해 트리거되는 시작 세션 이벤트에 포함합니다. 백엔드는 이 데이터를 처리하여 푸시 알림 터치포인트를 어트리뷰션하고 리인게이지먼트 추적을 등록합니다.
-
도메인 제한: 링크 관리 페이지의 Singular 링크 도메인(
sng.link)만 기본적으로 허용됩니다.WithESPDomains()을 사용하여 래핑된 링크에 대해 명시적으로 ESP 도메인을 구성하세요. -
플랫폼 차이점: iOS는 종료 상태 알림을 자동으로 처리하는 반면, Android는
SingularUnityActivity을 확장해야 자동 처리가 가능합니다.
성공: 이 단계를 수행하면 이제 앱에서 Singular와 푸시 알림 상호작용을 추적하여 캠페인 성과 인사이트를 개선하고 정확한 리인게이지먼트 어트리뷰션을 보장할 수 있습니다.