SDKをプロジェクトに追加する

Singular React SDKをプロジェクトに追加します：

1. プロジェクトのルートディレクトリでターミナルを開きます。

2. 以下のコマンドでSDKパッケージをプロジェクトにダウンロードします：

   npm install singular-react-native --save

3. React Native0.60以上を使用している場合は、Singularパッケージがプロジェクトに自動リンクされます。

   React Nativeバージョン0.59以前を使用している場合は、以下を実行して、Singularパッケージからネイティブブリッジコードをプロジェクトにリンクします：

   react-native link singular-react-native

前提条件の設定

iOSの前提条件

プロジェクトのルート・ディレクトリで、以下のコマンドを実行します：

cd ios; pod install

Androidの前提条件

allprojectsセクション内の build.gradleファイルで、アプリのMavenリポジトリに以下を追加します：

allprojects {
  repositories {
    maven { url 'https://maven.singular.net/' }
  }
}

アプリの AndroidManifest.xmlファイルに次のパーミッションを追加します：

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

<!--  このパーミッションは、Google Playのリファラーデータを取得するために必要です。  -->
<uses-permission android:name="com.google.android.finsky.permission.BIND_GET_INSTALL_REFERRER_SERVICE" />

<!--  このパーミッションは、google licensing APIからデータを取得するために必要です。  -->
<uses-permission android:name="com.android.vending.CHECK_LICENSE" />

アプリのビルドがAndroid 12/APIレベル31以上をターゲットにしている場合は、Google Advertising IDにアクセスするためのパーミッションを追加します：

<uses-permission android:name="com.google.android.gms.permission.AD_ID" />

Singular SDK の推移的依存関係を無効にしている場合は、アプリの build.gradle.

implementation 'com.android.installreferrer:installreferrer:2.2'
implementation 'com.google.android.gms:play-services-appset:16.0.0'

SDKの初期化

SDK初期化コードは、アプリを開くたびに呼び出す必要があります。これはSingularのすべてのアトリビューション機能の前提条件であり、またSingularに新しいユーザーセッションを送信します。セッションはユーザーのリテンションを計算するために使用されます。

必須クラスのインポート

App.js ファイルに以下のコードを追加し、Singular クラスと SingularConfigs クラスをインポートします。

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

SDKの設定と初期化

1. Singular SDKを初期化する前に、SingularConfigオブジェクトを作成する必要があります。このオブジェクトにはSDKキーとSDKシークレットが含まれます（SDKキーはSingularアカウントにログインし、"Developer Tools > SDK Integration > SDK Keys "で取得できます）。
2. オプションで、さまざまなSDK機能を有効にする設定を追加できます。
3. METAインストール・リファラー帰属のサポート

   Meta Install Referrer」アトリビューションを有効にするために必要なSDK設定です：

   1. Singular構成オブジェクトにFacebookアプリIDを入力してください。
      

      // META インストールリファラーを有効にするには
      config.withFacebookAppId("ここに Facebook アプリ ID を入力してください");

   アプリのFacebookアプリIDはどこで確認できますか？
4. 次に、init メソッドを使用して SDK を初期化します。 SingularConfigオブジェクトを渡します：

例えば

const config = new SingularConfig('<SDK KEY>', '<SDK SECRET>');
  
 // オプション設定：
 // 初期化時にユーザーIDがわかっている場合は、ユーザーIDを設定する。
 config.withCustomUserId("274e9db5c836093499df921be5b7f32001d49c50"); 
  
 // METAインストール・リファラーを有効にするには
 config.withFacebookAppId("INSERT YOUR FACEBOOK APP ID HERE");
  
 // ディープ・リンクが可能
 config.withSingularLinks(callBackFunction); 
  
 Singular.init(config);

Singular.init(config);

ユーザーIDをSingularに送信する（オプション）

Singular SDKのメソッドを使用して内部ユーザーIDをSingularに送信することができます。

• ユーザーIDはどのような識別子でもかまいませんが、PII（個人を特定できる情報）を公開するべきではありません。 例えば、ユーザーのメールアドレス、ユーザー名、電話番号は使用しないでください。Singularは、ファーストパーティデータにのみユニークなハッシュ値を使用することを推奨します。
• Singularに渡すユーザーIDは、すべてのプラットフォーム（ウェブ/モバイル/PC/コンソール/オフライン）で同じ内部ユーザーIDを使用する必要があります。
• Singularはユーザーレベルのエクスポート、ETL、内部BIポストバック（設定されている場合）にユーザーIDを含めます。ユーザーIDはファーストパーティデータであり、Singularが他者と共有することはありません。
• ユーザーIDの値は、Singular SDKメソッドで設定されると、unsetCustomUserId メソッドで設定が解除されるまで、またはアプリがアンインストールされるまで保持されます。アプリを終了または再起動しても、ユーザーIDはアンセットされません。

ユーザーIDを設定するには、setCustomUserId メソッドを使用します。設定を解除するには（ユーザがアカウントから「ログアウト」した場合など）、unsetCustomUserId を呼び出してください。

アプリを開いたときにユーザーIDがすでに分かっている場合は、Singular SDKを初期化する前にsetCustomUserId 。こうすることで、Singularは最初のセッションからユーザーIDを持つことができます。しかし、ユーザーIDは通常、ユーザーが登録するかログインを実行するまで使用できません。その場合は、登録フローが完了した後にsetCustomUserId 。

Singular.setCustomUserId("custom_user_id");

Singular.unsetCustomUserId();

Singular.setDeviceCustomUserId("CustomUserId");

AppTrackingTransparencyの同意の処理

iOS 14.5から、トラッキングのためにデバイスのIDFAにアクセスする前に、（ATTrackingManagerを使って）ユーザーの同意を求める必要があります。

ユーザーに同意を求める前にSingular SDKを初期化したい場合は、ユーザーの同意を待つために、SDKがIDFAなしでイベントを発生するのを指定した時間だけ遅らせることができます。

これを行うには、次の例のようにwaitForTrackingAuthorizationWithTimeoutIntervalオプションでSingular SDKを初期化します：

const config = new SingularConfig('<SDK KEY>', '<SDK SECRET>');
  
// SKAdNetworkを有効にする
config.withSkAdNetworkEnabled(true);
  
// イベントを送信する前に、トラッキングの承認を5分待つ。
config.withWaitForTrackingAuthorizationWithTimeoutInterval(300);
  
Singular.init(config);

イベントのトラッキング（非収入）

Singularはアプリ内イベントのデータを収集し、キャンペーンのパフォーマンス分析やKPIの測定に役立てることができます。例えば、ゲームアプリでユーザーのログイン、登録、チュートリアルの完了、レベルアップなどのデータを収集したいと思うかもしれません。

Singularは様々な 標準イベントをサポートしています。 これらの一般的に使用されるイベントは、レポートや最適化のために広告ネットワークによってサポートされることがよくあります。もう一つの利点は、標準的なイベント名を使用すると、Singularが自動的に認識し、手動で定義しなくてもイベントリストに追加されることです。可能な限り標準イベントを使用することをお勧めします。

Singularに送信されるイベントのリスト（付随する属性付き）は、組織のマーケティングKPIに基づいてUA/マーケティング/ビジネスチームが作成する必要があります。ビジネスチームは、How to Track In-App Eventsのガイドに従ってください：Guide For Singular Attribution Customers.

イベントごとに推奨される標準属性を参照してください。

コード内で、eventまたはeventWithArgsメソッドを使用してSingularにイベントを送信します。

/* 標準イベントログインの送信 */
Singular.event(sngLogin);

/* 標準イベント・コンテンツ・ビューに推奨属性を付けて送信する。 */
Singular.eventWithArgs(sngContentView, { 
  sngAttrContentType: 'PrivacyController',
  sngAttrContentId: '130',
  sngAttrContent: 'GDPR Opt-Out Options'
});

収益のトラッキング

Singularはアプリを通して得た収益に関するデータを収集し、キャンペーンのパフォーマンスやROIの分析に役立てることができます。Singularはレポート、ログエクスポート、ポストバックでデータを利用できるようにします。

収益イベントをSingularに報告する際は、AndroidまたはiOSのアプリ内課金（IAP）プロセスから返される購入オブジェクトを渡すことをお勧めします。こうすることで、Singularはトランザクションの詳細をすべて取得し、Singularのレポートをデータで豊かにします。さらに、SingularはGoogleからトランザクションのレシートを取得し、アプリ内詐欺対策としてトランザクションの検証に使用できます。

React Nativeで購入オブジェクトを渡す

// Singular Purchaseクラスのインポートを追加
import {
   Singular,
   SingularConfig,
   SingularIOSPurchase,
   SingularAndroidPurchase,
  } from 'singular-react-native';
  
  let singularPurchase = null;
  
  if (Platform.OS === 'ios') {
   singularPurchase = new SingularIOSPurchase(
     product.revenue,
     product.currency,
     purchase.productId,
     purchase.transactionId,
     purchase.transactionReceipt,
   );
  } else if (Platform.OS === 'android'){
   singularPurchase = new SingularAndroidPurchase(
     product.revenue,
     product.currency,
     purchase.transactionReceipt,
     purchase.signatureAndroid,
   );
  }
  
  Singular.inAppPurchase('report iap', singularPurchase);

ネイティブコードで購入オブジェクトを渡す

iOS

// 取引の詳細をSingularに報告する。
[Singular iapComplete:transaction];
  
// トランザクションの詳細をカスタム名でSingularに報告する。
[Singular iapComplete:transaction withName:@"MyCustomRevenue"];

Android

AndroidのIAP機能を利用するには、まずアプリの build.gradleファイルに追加します：

implementation 'com.singular.sdk:singular_sdk:9.+

Singular.revenue("USD", 5.50, purchase);

Singular.customRevenue("MyCustomRevenue", 
    "USD", 5.50, purchase);

購入オブジェクトなしで収益イベントを報告する

上記の方法で収益イベントを報告することを強く推奨しますが、通貨と取引額を渡すだけで収益イベントを Singular に送信することもできます。この方法では、Singularは購入レシートを取得せず、トランザクションを検証できないことに注意してください。

Singular.revenue("USD", 5.50);

Singular.customRevenue("MyCustomRevenue", "USD", 5.50);

広告収益アトリビューションサポートの追加（上級者向け）

ハイブリッドイベントトラッキング（上級者向け）

Singularでは、アプリに統合されたSingular SDKを通してすべてのイベントと収益を送信することを推奨しています。ただし、Singularは他のソースからイベントと収益を収集することもできます。

Singular SDKから送信されないイベントは、Singularのサーバー間イベントドキュメンテーション要件に準拠し、イベントの属性を正しく設定するために一致するデバイス識別子を提供する必要があります。

ハイブリッドイベント追跡ガイド

ディープリンクサポートの追加

ディープリンクは、アプリ内の特定のコンテンツにつながるリンクです。アプリがインストールされたデバイスでユーザーがディープリンクをクリックすると、アプリが開き、特定の製品や体験が表示されます。

シンギュラートラッキングリンクは、ディープリンクだけでなく、ディファードディープリンクも含むことができます（詳しくは、 ディープリンクFAQと シンギュラートラッキングリンクFAQをご覧ください）。

以下の手順で方法を説明します：

1. アプリを開くきっかけとなったトラッキングリンクにアクセスする、
2. ディープリンク先を読み取る
3. 適切なコンテンツを表示する。

Singular Linksを有効にする

iOSとAndroidでSingular Linksを有効にするには、Singular Linksの前提条件をご覧ください。

シンギュラーリンクの処理

Singular SDKは、アプリを開くきっかけとなったトラッキングリンクの詳細を読み取るためのハンドラーメカニズムを提供します。

ハンドラを使用するには

1. ハンドラを使うには withSingularLinksを呼び出します。これでSingular Linksハンドラが登録されます。
2. ハンドラ内で、以下の例のように SingularLinksParams オブジェクトを受け取るコールバック関数を呼び出すか定義します。SingularLinksParamsオブジェクトには以下のフィールドがあります：
   • deeplink- クエリパラメータで指定されたディープリンクアドレス。 _dlクエリパラメータで指定されたディープリンクアドレス。 これは、ユーザーに適切な製品や体験を表示するために解析する必要があるものです。
   • passthrough- のクエリパラメータに含まれるすべてのパラメータ。 _pクエリパラメータに含まれるすべてのパラメータ。
   • isDeferred- 遅延ディープリンクの場合はtrue。
   • urlParameters- Singular Tracking Link のすべてのクエリ文字列パラメータ。
     • すべてのクエリ文字列パラメータを指定するには _forward_params=1 キーと値のペアを Singular Tracking Link に追加する必要があります。

const config = new SingularConfig('<SDK KEY>', '<SDK SECRET>');
  config.withSingularLink(singularLinksParams => {
      const deeplink = singularLinksParams.deeplink;
      const passthrough = singularLinksParams.passthrough;
      const isDeferred = singularLinksParams.isDeferred;
      const urlParameters = singularLinksParams.urlParameters;
      
      // ディープリンクを処理するコードをここに追加する
  });
  //...
  Singular.init(config);

前提条件の設定

iOSの前提条件

プロジェクトの AppDelegate.mに以下を追加する：

// AppDelegate.mトップ
  #import <Singular-React-Native/SingularBridge.h>
  
  - (BOOL)application:(UIApplication *)application 
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
      // didFinishLaunchingWithOptions 内に追加する。
      [SingularBridge startSessionWithLaunchOptions:launchOptions];
    return YES;
  }
  
  // このメソッドをアプリのデリゲートに追加する
  - (BOOL)application:(UIApplication *)application 
    continueUserActivity:(NSUserActivity *)userActivity 
      restorationHandler:(void (^)(NSArray<id> * _Nullable))restorationHandler{
        [SingularBridge startSessionWithUserActivity:userActivity];
        return YES;
  }

Androidの前提条件

プロジェクトの MainActivity.javaに以下を追加する：

// クラスの先頭にインポートの一部として追加する。
import android.content.Intent;
import net.singular.react_native.SingularBridgeModule;
  
// MainActivityクラスに追加
  @Override
  public void onNewIntent(Intent intent) {
    if(intent.getData() != null) {
      setIntent(intent);
      super.onNewIntent(intent);
      SingularBridgeModule.onNewIntent(intent);
    }
  }

はじめにSKAdNetworkとSKAN

SKAdNetworkは、エンドユーザーのプライバシーを損なうことなくモバイルインストールを帰属させるためのAppleの新しいフレームワークです。Singularの新バージョンのiOS SDKは、SKAdNetworkをシームレスに最小限のエンジニアリング労力で実装するのに役立ちます。このSKAdNetworkの実装はSKAN-SKAdNetworkをスムーズに実装するためにSingularが開発した標準-に基づいています。

SingularのSKAdNetwork実装の詳細については、 iOS SDK SKAdNetwork実装ガイドをご覧ください。

SKAdNetwork トラッキングの有効化

アプリの SKAdNetwork トラッキングを有効にするには、Singular を初期化する前に skAdNetworkEnabled 設定オプションをオンにします：

const config = new SingularConfig('<SDK KEY>', '<SDK SECRET>');

// SKAdNetworkを有効にする
config.withSkAdNetworkEnabled(true);

// 変換値が更新されたときのコールバックへの登録
config.conversionValueUpdatedHandler(value => {
	console.log(`Updated conversion value: ${value}`);
  });

Singular.init(config);

コンバージョン値の更新処理

マネージドモード

デフォルトでは、SKAdNetworkの実装はSingularサーバーサイドから直接コンバージョン値を管理します。

これにより、クライアント側のコードを変更することなく、Singularプラットフォームを通してコンバージョン値を設定、変更することができるため、最大限の柔軟性が得られます。

このサーバー側の管理モードは、SKAdNetworkのタイマーの処理にも役立ちます。SKAdNetworkでは、SKAdNetworkへの登録から24時間以内にコンバージョン値を更新することができます。コンバージョン値の更新を呼び出すと、タイマーはさらに24時間延長されます。そのため、コンバージョンイベントを選択する際は、その更新ウィンドウ内でイベントが発生するようにする必要があります。マネージドモードでは、アプリの新しいバージョンをリリースすることなく、いつでもコンバージョンイベントの設定を変更することができます。

手動モード

アプリのコードで独自に変換値を更新したい場合は、SDKを初期化するときにwithManualSkanConversionManagementを呼び出します：

const config = new SingularConfig('<SDK KEY>', '<SDK SECRET>');
// SKAdNetworkを有効にする
config.withSkAdNetworkEnabled(true);

// 変換値の手動更新を有効にする
config.withManualSkanConversionManagement();

Singular.init(config);

その後、変換値を更新するには、アプリのライフサイクル内の必要な場所でskanUpdateConversionValueメソッドを使用します：

// サイン会開催
Singular.event("SignUp");

// 変換値を7に更新
Singular.skanUpdateConversionValue(7);

変換値の取得

現在の変換値を取得するには、skanGetConversionValueメソッドを使用します。このメソッドは、マネージドモードでもマニュアルモードでも動作します。

const conversionValue = Singular.skanGetConversionValue();

短いリファラーリンクの作成

ショートリンクを使用すると、長いパラメータいっぱいのSingularリンクを、共有に便利な短くて安全なリンクに変換できます。

通常、ショートリンクを動的に作成し、アプリのユーザーが友人と共有し、アプリの使用を招待できるようにします。

ショートリンクを作成するには

• アプリのダウンロードにつながるシンギュラーリンク（シンギュラーリンクのFAQを参照）。
• リンクに動的に追加したいパラメータ（オプションの一覧はトラッキングリンクパラメータをご覧ください）。
• アプリの新規インストールを、リンクを共有したユーザーまで追跡したい場合は、参照ユーザーの名前とID。

以下の例のようにショートリンクを作成するには、createReferrerShortLinkメソッドを使用します。

Singular.createReferrerShortLink (
    "https://sample.sng.link/B4tbm/v8fp?_dl=https%3A%2F%2Fabc.com",
    "John Doe", // 紹介者名
    "aq239897", // リファラーID
    {"channel": "sms"}, // リンクに追加したいパラメータ
    (shortLinkURL,error) => {
      /* shortLinkURLがnullでない場合は、ここに共有ロジックを追加します。エラーが発生した場合は、エラーの原因に応じて、関数に渡されたパラメータを再試行/中止/変更するロジックを追加します。 */
    }
)

アンインストールの追跡

Singularでアプリのアンインストールを追跡するには、次のようにします：

1. まず、アンインストールトラッキングの設定 [Android][iOS]で説明するように、Singularプラットフォームでアプリを設定します。
2. お好みの方法を使用して、React Native でAPNS/FCMトークンを取得します。
3. 以下の例のように、APNS/FCM トークンを渡してsetUninstallTokenメソッドを呼び出します。デバイスのプラットフォームに応じて正しいトークンを渡すようにしてください。

if (Platform.OS === 'ios') {
  Singular.setUninstallToken(apnsToken);
} else if (Platform.OS === 'android'){
  Singular.setUninstallToken(fcmToken);
}

セッションタイムアウトの変更

Singularは、GDPRやCCPA（カリフォルニア州消費者プライバシー法）などの消費者プライバシー法を遵守している可能性のあるパートナーと協力するために、プライバシー保護機能を提供します。 これらのパートナーは、エンドユーザーが個人情報の共有に同意した場合に通知されることを望んでいます。

データ共有の制限

ユーザーに情報共有の同意を求める方法を実装している場合は、limitDataSharingメソッドを使用してユーザーの選択をSingularに通知します：

• limitDataSharing:NOを使用して、ユーザーが情報の共有に同意した (オプトインした) ことを示します。
• ユーザーが同意しなかった場合はlimitDataSharing:YES を使用します。

Singularは「ユーザープライバシーのポストバック」においてLimitDataSharingを使用し、関連法規を遵守するためにこの情報を必要とするパートナーに情報を提供します。詳しくは「ユーザーのプライバシーとデータ共有の制限」をご覧ください。

// ユーザーがデータ共有に同意した
Singular.limitDataSharing(false);

GDPR準拠のための追加メソッド

Singular SDKは、GDPRポリシーに準拠し、トラッキングに対するユーザーの同意または非同意についてSingularに知らせるためのメソッドをいくつか提供しています。

Singular.trackingOptIn();

Singular.stopAllTracking();

Singular.resumeAllTracking();

Singular.isAllTrackingStopped();