プッシュ通知のサポート

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

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

実装ガイド

Singular SDKを統合する

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

Firebase Cloud Messaging のセットアップ

@havesource/cordova-plugin-push のようなプラグインを使用して Cordova プロジェクトでプッシュ通知を設定し、Firebase のセットアップガイドに従ってプラットフォーム固有の統合を行います。

iOS の設定

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

1. iOS アプリを登録します：Firebase Console プロジェクトで iOS アプリを作成します。
2. 設定ファイルの追加: GoogleService-Info.plist をダウンロードし、iOS プラットフォームフォルダに含めます。
3. 機能を有効にする：Xcode のプロジェクト設定で、Push Notifications 機能を有効にします。
4. バックグラウンドモードを有効にする：Background Modes を有効にし、Remote notifications をチェックします。

Androidの設定

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

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

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

適切なアトリビューショントラッキングを可能にするために、プッシュ通知のペイロード構造内で Singular トラッキングリンクが配置される JSON パスを定義します。

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

// Create configuration
var config = new cordova.plugins.SingularCordovaSdk.SingularConfig(
  'YOUR_SDK_KEY',
  'YOUR_SDK_SECRET'
);

// Configure paths where Singular links appear in push payload
config.withPushNotificationsLinkPaths([
  ['sng_link'],                              // Top-level key
  ['path', 'to', 'url'],                     // Nested path
  ['rootObj', 'nestedObj', 'singularLink']   // Deep nested path
]);

// Initialize SDK
cordova.plugins.SingularCordovaSdk.init(config);

パスの構成例

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

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

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

ユーザーがプッシュ通知とインタラクションしたときに、アプリの状態に基づいてSingular SDKに通知データを渡すためのプラットフォーム固有のコードを設定します。

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

アプリが終了した状態

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

AppDelegate.m 内の iOS ネイティブコードで、didFinishLaunchingWithOptions 内の以下のメソッドを呼び出します：

// Import at the top of the file
#import <SingularCordovaSdk/SingularCordovaSdk.h>

- (BOOL)application:(UIApplication *)application 
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    
    // Pass launch options to Singular for push tracking
    [SingularCordovaSdk setLaunchOptions:launchOptions];
    
    // Your other initialization code
    return YES;
}

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

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

プッシュ通知を処理するJavaScriptコードで以下のメソッドを呼び出します：

// Handle push notification when app is in background or foreground
document.addEventListener('deviceready', initializePushHandling, false);

function initializePushHandling() {
  // Initialize push plugin
  var push = PushNotification.init({
    android: {},
    ios: {
      alert: true,
      badge: true,
      sound: true
    }
  });
  
  // Handle notification when app is in foreground or background
  push.on('notification', function(data) {
    console.log('Push notification received:', data);
    
    // Pass notification data to Singular
    cordova.plugins.SingularCordovaSdk.handlePushNotification(data.additionalData);
    
    // Your custom notification handling logic
    handleNotificationNavigation(data);
  });
}

function handleNotificationNavigation(data) {
  // Navigate to appropriate screen based on notification data
  if (data.additionalData && data.additionalData.route) {
    console.log('Navigating to:', data.additionalData.route);
    // Your navigation logic
  }
}

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

Androidプッシュ通知の処理

終了状態のアプリ

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

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

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

Cordovaのメインアクティビティ（例：MainActivity.java ）で、onNewIntent をオーバーライドします：

// Add imports at the top
import android.content.Intent;
import singular_cordova_sdk.SingularCordovaSdk;

// Add to MainActivity class
@Override
protected void onNewIntent(Intent intent) {
    super.onNewIntent(intent);
    
    // Pass intent to Singular for push tracking
    SingularCordovaSdk.handleNewIntent(intent);
}

さらに、上記のiOSのバックグラウンド/フォアグラウンド処理と同じアプローチで、JavaScriptコードにプッシュメッセージ処理を実装します。

検証ガイド

Singular SDKの開始セッションコールを検査し、アトリビューションデータを監視することで、プッシュ通知トラッキングが正しく動作していることを確認します。

開始セッションのペイロードを確認する

APIコールパラメータの確認

開始セッション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.singularsampleapp
&install_time=1740905507036
&s=1740905574084
&sdk=Singular/v12.6.2
&singular_install_id=2dc5dfc2-a2a8-484a-aad1-fed6cb7a3023
&u=75f7b911-5a77-597d-8892-56f5e0e210ff

高度な構成

複雑な通知シナリオのために、ESPドメイン設定やダイナミックディープリンクルーティングなどの高度なプッシュ通知機能を実装します。

ESPドメイン構成

外部ドメインの構成

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

// Create configuration
var config = new cordova.plugins.SingularCordovaSdk.SingularConfig(
  'YOUR_SDK_KEY',
  'YOUR_SDK_SECRET'
);

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

// Initialize SDK
cordova.plugins.SingularCordovaSdk.init(config);

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

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

単一の通知からの複数のアクション

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

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

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

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

// Handle multiple deep link options from single notification
function handleNotificationWithActions(notificationData) {
  // Extract action selection from notification data
  var selectedAction = notificationData.action;
  var singularLink = notificationData.sng_link;
  
  // Route based on action
  switch (selectedAction) {
    case 'read_news':
      navigateToArticle(notificationData.article_id);
      break;
    case 'trending':
      navigateToTrending();
      break;
    case 'sports':
      navigateToSports();
      break;
    default:
      navigateToHome();
  }
  
  // Pass notification to Singular for attribution
  cordova.plugins.SingularCordovaSdk.handlePushNotification(notificationData);
}

function navigateToArticle(articleId) {
  console.log('Navigating to article:', articleId);
  // Your navigation logic
}

function navigateToTrending() {
  console.log('Navigating to trending');
  // Your navigation logic
}

function navigateToSports() {
  console.log('Navigating to sports');
  // Your navigation logic
}

function navigateToHome() {
  console.log('Navigating to home');
  // Your navigation logic
}

重要な考慮事項

プッシュ通知トラッキングをSingular SDKと統合する際の重要な実装の詳細と制限を理解してください。

実装上の注意

主な動作と制限

• コールバックハンドラはありません： withSingularLink と異なり、プッシュ通知機能はペイロードコールバックを提供しません。独自のディープリンクロジックを実装して、通知データに基づいてアプリ内の特定のコンテンツにユーザーをルーティングする必要があります。
• アトリビューションフロー：ユーザーが通知をタップすると、Singularはペイロードを取得し、Singular.init(config) によってトリガーされるセッション開始イベントに含めます。バックエンドはこのデータを処理して、プッシュ通知のタッチポイントに属性を付け、リエンゲージメント追跡を登録します。
• ドメインの制限：デフォルトでは、[Manage Links（リンクの管理）]ページにあるSingularリンクドメイン（sng.link ）のみが許可されています。ラップリンク用のESPドメインは、withESPDomains()を使用して明示的に設定します。
• プラットフォームの違い:iOSでは、終了状態の処理にAppDelegateの設定が必要ですが、Androidでは、終了状態のシナリオに対してブリッジモジュールを通じて自動的に処理されます。
• パスの設定：SDKは、withPushNotificationsLinkPaths() で定義されたパスを使用してSingularリンクを検索します。通知ペイロード構造が、適切なリンク抽出のために構成されたパスに一致することを確認してください。

テストに関する推奨事項

1. すべてのアプリの状態をテストする：アプリが終了しているとき、バックグラウンドのとき、フォアグラウンドのときにプッシュトラッキングが正しく動作することを確認する。
2. ペイロード構造の検証：通知ペイロードが設定されたパスにSingularリンクを含むことを確認する。
3. セッション・コールの開始を確認する：ネットワーク監視ツールを使用して、セッション開始リクエストにsingular_link パラメータが表示されることを確認します。
4. 属性の監視Singular SDKコンソールをチェックし、プッシュ通知がキャンペーンデータに正しく帰属していることを確認します。
5. ディープリンクのテスト：さまざまな通知タイプをタップしたときに、ユーザーが意図したコンテンツに正しく移動していることを確認します。