ドキュメント

プッシュ通知のサポート

Firebase Cloud Messaging (FCM) とSingular SDKを統合することで、プッシュ通知によるユーザーインタラクションを追跡し、リエンゲージメントキャンペーンやコンバージョン率を正確に測定することができます。

以下の実装ガイドラインに従って、通知データが正しくSingular SDKに渡され、適切なアトリビューションが行われるようにしてください。

プッシュ通知を追跡する理由プッシュ通知はリエンゲージメントを促進しますが、トラッキングには正しい統合が必要です。Singularは、通知を受け取ったユーザーが適切にアトリビューションされるようにし、マーケティングキャンペーンとエンゲージメント戦略を最適化します。

実装ガイド

Singular SDKを統合する

Singular React Native SDKガイドに記載されている標準的なインストール手順を使用して、Singular SDKをReact Nativeプロジェクトに統合します。

Firebase Cloud Messaging のセットアップ

Firebase パッケージをインストールし、プッシュ通知をサポートするためのプラットフォーム固有の設定を行います。

Firebase パッケージのインストール

コア機能とメッセージングサポートのために、React Native Firebase の依存関係を追加します。

npm install @react-native-firebase/app
npm install @react-native-firebase/messaging

iOS の設定

iOS アプリを Firebase に登録し、Xcode でプッシュ通知機能を設定します。

iOS アプリを登録します：Firebase Console プロジェクトで iOS アプリを作成します。
Add Configuration File: GoogleService-Info.plist をダウンロードし、Xcode プロジェクトに追加します。
機能を有効にする：Xcodeプロジェクトの設定で、プッシュ通知機能を有効にする。
バックグラウンドモードを有効にする：バックグラウンドモードを有効にし、リモート通知をチェックする。

Androidの設定

AndroidアプリをFirebaseに登録し、設定ファイルをプロジェクトに追加します。

Androidアプリを登録します：Firebase ConsoleプロジェクトにAndroidアプリを作成します。
設定ファイルの追加: google-services.json をダウンロードし、android/app/に配置します。
依存関係を確認します：Firebase メッセージングの依存関係が追加され、パーミッションが付与されていることを確認します。

プッシュリンクパスの設定

プッシュ通知ペイロード構造内でSingularトラッキングリンクが配置されるJSONパスを定義します。

プッシュリンクパスを設定するには、通知データ構造内のSingularリンクへのキーパスを指定する文字列の配列を渡します。各パスはキーの入れ子構造を表す配列です。

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';

const config: SingularConfig = {
  apikey: 'YOUR_SDK_KEY',
  secret: 'YOUR_SDK_SECRET',
  pushNotificationsLinkPaths: [
    ['sng_link'],                            // Top-level key
    ['path', 'to', 'url'],                   // Nested path
    ['rootObj', 'nestedObj', 'singularLink'] // Deep nested path
  ]
};

NativeSingular.init(config);

import { Singular, SingularConfig } from 'singular-react-native';

const config = new SingularConfig(
  'YOUR_SDK_KEY',
  'YOUR_SDK_SECRET'
)
  .withPushNotificationsLinkPaths([
    ['sng_link'],                              // Top-level key
    ['path', 'to', 'url'],                     // Nested path
    ['rootObj', 'nestedObj', 'singularLink']   // Deep nested path
  ]);

Singular.init(config);

パスの構成例

単純なキーペイロードのトップレベルのキーには['sng_link'] を使用します。
ネストされたキー：ネストした JSON 構造をトラバースするには['rootObj', 'nestedObj', 'key'] を使用する。
複数のパス：複数のパス配列を定義して、Singularリンクのさまざまな可能性のある場所をチェックする。

メソッドの完全なドキュメントについては、withPushNotificationsLinkPathsリファレンスを参照してください。

プラットフォーム固有の処理

iOSプッシュ通知ハンドリング

終了状態のアプリ

iOS AppDelegateを設定して、アプリが終了した状態から開いたときに、Singular SDKに起動オプションを渡して自動プッシュトラッキングを行うようにします。

AppDelegate で、didFinishLaunchingWithOptions 内に以下を追加します：

// Import at the top of the file
import Singular

func application(
  _ application: UIApplication,
  didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
) -> Bool {
  let delegate = ReactNativeDelegate()
  let factory = RCTReactNativeFactory(delegate: delegate)
  delegate.dependencyProvider = RCTAppDependencyProvider()

  reactNativeDelegate = delegate
  reactNativeFactory = factory

  window = UIWindow(frame: UIScreen.main.bounds)

  if let singularBridge = NSClassFromString("SingularBridge") {
    let selector = NSSelectorFromString("startSessionWithLaunchOptions:")
    if singularBridge.responds(to: selector) {
      singularBridge.perform(selector, with: launchOptions, afterDelay: 1)
    }
  }

  factory.startReactNative(
    withModuleName: "YourAppName", // Update with your App Name
    in: window,
    launchOptions: launchOptions
  )

  return true
}

// Import at the top of the file
#import <Singular-React-Native/SingularBridge.h>

- (BOOL)application:(UIApplication *)application 
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    // Pass launch options to Singular for push tracking
    [SingularBridge startSessionWithLaunchOptions:launchOptions];

    // Your other initialization code
    return YES;
}

自動処理：アプリが実行されていない状態でユーザーがプッシュ通知をタップすると、Singularは起動オプションを通してアプリ起動時に通知ペイロードを自動的にキャプチャします。

アプリのバックグラウンドまたはフォアグラウンド

アプリがバックグラウンドまたはフォアグラウンドの状態で通知を受信した場合、handlePushNotification() メソッドを使用して SDK にプッシュデータを渡します。

// TurboModule direct API (React Native 0.76+ New Architecture)
import React, { useEffect } from 'react';
import NativeSingular from 'singular-react-native/jsNativeSingular';
import messaging from '@react-native-firebase/messaging';

export default function App() {
  useEffect(() => {
    // Handle foreground messages
    const unsubscribeBackground = messaging().onMessage(handleForegroundMessage);

    // Handle messages that opened the app from background
    messaging().onNotificationOpenedApp(handleBackgroundMessage);

    return () => {
      unsubscribeBackground();
    };
  }, []);

  function handleForegroundMessage(remoteMessage) {
    console.log('Foreground message received:', remoteMessage);

    // Pass notification data to Singular
    if (remoteMessage.data) {
      NativeSingular.handlePushNotification(remoteMessage.data);
    }

    // Your custom notification handling
    displayLocalNotification(remoteMessage);
  }

  function handleBackgroundMessage(remoteMessage) {
    console.log('Background message opened app:', remoteMessage);

    // Pass notification data to Singular
    if (remoteMessage.data) {
      NativeSingular.handlePushNotification(remoteMessage.data);
    }

    // Navigate to appropriate screen
    navigateFromNotification(remoteMessage);
  }

  function displayLocalNotification(remoteMessage) {
    // Your notification display logic
    console.log('Displaying notification:', remoteMessage.notification?.title);
  }

  function navigateFromNotification(remoteMessage) {
    // Your navigation logic based on notification data
    const route = remoteMessage.data?.route;
    console.log('Navigating to:', route);
  }

  return (
    // Your app components
    null
  );
}

import React, { useEffect } from 'react';
import { Singular } from 'singular-react-native';
import messaging from '@react-native-firebase/messaging';

export default function App() {
  useEffect(() => {
    // Handle background messages
    const unsubscribeBackground = messaging().onMessage(handleForegroundMessage);

    // Handle messages that opened the app from background
    messaging().onNotificationOpenedApp(handleBackgroundMessage);

    return () => {
      unsubscribeBackground();
    };
  }, []);

  function handleForegroundMessage(remoteMessage) {
    console.log('Foreground message received:', remoteMessage);

    // Pass notification data to Singular
    if (remoteMessage.data) {
      Singular.handlePushNotification(remoteMessage.data);
    }

    // Your custom notification handling
    displayLocalNotification(remoteMessage);
  }

  function handleBackgroundMessage(remoteMessage) {
    console.log('Background message opened app:', remoteMessage);

    // Pass notification data to Singular
    if (remoteMessage.data) {
      Singular.handlePushNotification(remoteMessage.data);
    }

    // Navigate to appropriate screen
    navigateFromNotification(remoteMessage);
  }

  function displayLocalNotification(remoteMessage) {
    // Your notification display logic
    console.log('Displaying notification:', remoteMessage.notification?.title);
  }

  function navigateFromNotification(remoteMessage) {
    // Your navigation logic based on notification data
    const route = remoteMessage.data?.route;
    console.log('Navigating to:', route);
  }

  return (
    // Your app components
  );
}

メソッドの詳細については、handlePushNotificationリファレンスを参照してください。

Androidプッシュ通知ハンドリング

終了状態のアプリ

終了状態のAndroidアプリには何もする必要はありません。React Nativeブリッジレイヤーは、ユーザーが通知をタップすると、このシナリオを自動的に処理します。

自動処理：アプリが実行されていない状態でユーザーがプッシュ通知をタップすると、Singularはネイティブブリッジの統合を通じて通知データを自動的に取得します。

アプリのバックグラウンドまたはフォアグラウンド

アプリがバックグラウンドまたはフォアグラウンド状態の時にSingular SDKに通知インテントを渡すようにAndroid MainActivityを設定します。

MainActivity（MainActivity.java やMainActivity.kt など）で、onNewIntent をオーバーライドします：

// Add imports at the top
import android.content.Intent;
import net.singular.react_native.SingularBridgeModule;

// Add to MainActivity class
@Override
protected void onNewIntent(Intent intent) {
    super.onNewIntent(intent);

    // Pass intent to Singular for push tracking
    SingularBridgeModule.onNewIntent(intent);
}

// Add imports at the top
import android.content.Intent
import net.singular.react_native.SingularBridgeModule

// Add to MainActivity class
override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)

    // Pass intent to Singular for push tracking
    SingularBridgeModule.onNewIntent(intent)
}

さらに、上記のiOSのバックグラウンド/フォアグラウンド処理と同じ方法で、React NativeコードにFirebaseメッセージ処理を実装します。

検証ガイド

セッション開始時のペイロードの検証

開始セッション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=net.singular.sampleapp
&s=1740905574084
&sdk=Singular/React-Native-v1.0.0

代替検証：Singular SDKコンソールを使用して、プッシュ通知のトラッキングを確認します。ディープリンクURLフィールドをチェックして、トラッキングリンクが正しくキャプチャされていることを確認します。

高度な構成

ESPドメイン設定

SingularリンクをEメールサービスプロバイダ（ESP）またはその他のサードパーティのドメインでラップする場合は、外部ドメインを設定します。

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';

// Configure ESP domains for wrapped Singular links
const config: SingularConfig = {
  apikey: 'YOUR_SDK_KEY',
  secret: 'YOUR_SDK_SECRET',
  espDomains: ['sl.esp.link', 'custom.domain.com']
};

NativeSingular.init(config);

import { Singular, SingularConfig } from 'singular-react-native';

// Configure ESP domains for wrapped Singular links
const config = new SingularConfig(
  'YOUR_SDK_KEY',
  'YOUR_SDK_SECRET'
)
  .withESPDomains(['sl.esp.link', 'custom.domain.com']);

Singular.init(config);

セキュリティ上の注意：デフォルトでは、Singularリンク管理ページで事前に定義されたドメイン（sng.link）のみが許可されます。ラップリンクを使用する場合は、ESPドメインを明示的に設定します。

方法の詳細については、withESPDomainsリファレンスを参照してください。

ダイナミック・ディープ・リンク・ルーティング

ダイナミックリダイレクトオーバーライドで1つのSingularトラッキングリンクを設定することで、1つの通知から複数のディープリンク先を実装します。

使用例複数のアクションオプションを持つニュース速報

最新ニュースを読む:newsapp://article?id=12345
トレンドトピック newsapp://trending
スポーツ newsapp://sports

複数のトラッキングリンクを作成する代わりに、1つのSingularリンクを使用し、ユーザーの選択に基づいて動的にリダイレクトを上書きします。実装の詳細については、Singular トラッキングリンクでリダイレクトを上書きするを参照してください。

重要な考慮事項

実装上の注意

コールバックハンドラはありません： withSingularLink と異なり、プッシュ通知機能はペイロードコールバックを提供しません。独自のディープリンクロジックを実装して、ユーザーをアプリ内の特定のコンテンツに誘導してください。
アトリビューションフロー：ユーザーが通知をタップすると、Singularはペイロードを取得し、SDKの初期化によってトリガーされるセッション開始イベントに含めます。バックエンドはこのデータを処理し、プッシュ通知のタッチポイントをアトリビューションし、リエンゲージメント・トラッキングを登録します。
ドメインの制限デフォルトでは、[Manage Links（リンクの管理）]ページからの単一リンクドメイン（sng.link ）のみが許可されます。ラップリンク用のESPドメインは、withESPDomains()を使用して明示的に設定します。
プラットフォームの違い:iOSでは終了状態のためにAppDelegateの設定が必要ですが、Androidではブリッジモジュールによって自動的に処理されます。

成功：これらのステップに従うことで、あなたのアプリはSingularでプッシュ通知のインタラクションをトラッキングし、キャンペーンパフォーマンスのインサイトを改善し、正確なリエンゲージメントアトリビューションを保証します。

React Native SDK - プッシュ通知のサポート

プッシュ通知のサポート

実装ガイド

Singular SDKを統合する

Firebase Cloud Messaging のセットアップ

Firebase パッケージのインストール

iOS の設定

Androidの設定

プッシュリンクパスの設定

プラットフォーム固有の処理

iOSプッシュ通知ハンドリング

終了状態のアプリ

アプリのバックグラウンドまたはフォアグラウンド

Androidプッシュ通知ハンドリング

終了状態のアプリ

アプリのバックグラウンドまたはフォアグラウンド

検証ガイド

セッション開始時のペイロードの検証

高度な構成

ESPドメイン設定

ダイナミック・ディープ・リンク・ルーティング

重要な考慮事項

実装上の注意