React Native SDK

これはAmplitude Analytics React Native SDKの公式ドキュメントです。

互換性マトリックス

次の表は、React NativeおよびReact Native CLIの各バージョン間でサポートされているAmplitude React Native SDKのバージョンを示しています。

Android Gradleプラグインの互換性について詳しくはこちらをご覧ください。

SDKをインストールする

プロジェクトディレクトリのpackage.jsonと同じレベルでyarn add @amplitude/react-nativeを実行します。

yarn add @amplitude/react-native

iOSのインストール

cd ios && pod install

SDKの初期化

インストルメントする前に、AmplitudeプロジェクトのAPIキーを使用してSDKを初期化してください。

import * as React from 'react';
import { Button } from 'react-native';
import { Amplitude, Identify } from '@amplitude/react-native';
const ampInstance = Amplitude.getInstance();
ampInstance.init(AMPLITUDE_API_KEY);
export function MyApp() {
    return (
    <Button
        title="Log Event"
        onPress=() => ampInstance.logEvent('BUTTON_CLICKED')
    />
    );
}

SDK を設定する

Amplitude React Native SDKは、Amplitude Android Maintenance SDKとAmplitude iOS Maintenance SDKの上で動作します。 次の ts/js 設定オプションを設定できます。 その他のデフォルト設定の場合：

• Androidの場合は、Android設定を参照してください。
• iOSの場合は、iOS設定を参照してください。

バッチ処理の動作を設定する

高パフォーマンス環境をサポートするために、SDK はイベントをバッチで送信します。 logEventメソッドは、メモリ内のすべてのイベントをキューに登録します。SDKはバックグラウンドで、イベントをバッチ単位でフラッシュします。setEventUploadThresholdおよびsetEventUploadPeriodMillisを使用してバッチ動作をカスタマイズできます。 デフォルトでは、serverUrl は https://api2.amplitude.com/ です。 この SDK は、バッチ API エンドポイント経由でのバッチモードをサポートしていません。

// Events queued in memory will flush when number of events exceed upload threshold
// Default value is 30
Amplitude.getInstance().setEventUploadThreshold(100);
// Events queue will flush every certain milliseconds based on setting
// Default value is 30 second.
Amplitude.getInstance().setEventUploadPeriodMillis(100000);

EU域内のデータレジデンシー

バージョン2.6.0以降では、クライアントを初期化した後にサーバーゾーンを設定してAmplitudeのEUサーバーにデータを送信してください。 SDKは設定時にサーバーゾーンに基づいてデータを送信します。サーバゾーン設定は、動的設定もサポートしています。

以前のバージョンの場合、クライアントを初期化した後にserverURLプロパティを設定してください。

// For versions starting from 2.6.0
// No need to call setServerUrl for sending data to Amplitude's EU servers
Amplitude.getInstance().setServerZone('EU');
// For earlier versions
Amplitude.getInstance().setServerUrl("https://api.eu.amplitude.com"));

基本イベントを送信する

イベントは、ユーザーがアプリケーションとどのように対話するかを表します。 たとえば、「ボタンがクリックされた」というアクションは、追跡したいアクションかもしれません。

Amplitude.getInstance().logEvent("BUTTON_CLICKED");

プロパティ付きのイベントを送信

イベントには、イベントに関するコンテキストを提供するプロパティも含めることができます。たとえば、「ホバー時間」は、「ボタンのクリック」に関連するイベントプロパティである可能性があります。

Amplitude.getInstance().logEvent("BUTTON_CLICKED", { "Hover Time": "100ms" });

イベントをフラッシュする

SDK は通常、イベントをバッファに保存し、定期的にフラッシュします。 この動作は設定可能です。 イベントを手動でフラッシュすることもできます。

Amplitude.getInstance().uploadEvents();

ユーザープロパティ

ユーザープロパティは、ユーザーがアプリ内でアクションを実行した時点でのユーザーの状況を把握するのに役立ちます。ユーザーのデバイスの詳細情報、環境設定、言語などです。

Amplitude-ReactNativeのIdentifyクラスがこれらの機能を管理します。使用する前にIdentifyをインポートしてください。

import { Identify } from "@amplitude/react-native";

ユーザープロパティを設定する

setは、ユーザープロパティの値を設定します。また、複数のidentifyコールを連結することもできます。

const identify = new Identify();
identify.set("gender", "female").set("age", 20);
Amplitude.getInstance().identify(identify);

一度だけ設定

setOnceは、ユーザープロパティの値を1回だけ設定します。setOnceを使用した以降の呼び出しは無視されます。

const identify1 = new Identify();
identify1.setOnce("sign_up_date", "2015-08-24");
Amplitude.getInstance().identify(identify1);
const identify2 = new Identify();
identify2.setOnce("sign_up_date", "2015-08-24");
Amplitude.getInstance().identify(identify2); // is ignored

追加する

addはユーザープロパティを数値で増分します。ユーザープロパティに値がまだ設定されていない場合、SDK は値を増分する前に値を 0 に初期化します。

const identify = new Identify();
identify.add("karma", 0.123);
Amplitude.getInstance().identify(identify);

複数のユーザープロパティを設定する

複数のユーザープロパティを一度に設定する場合の省略形としてsetUserPropertiesを使用します。このメソッドは、Identify.set および identifyのラッパーです。

const userProperties = {
  KEY: "VALUE",
  OTHER_KEY: "OTHER_VALUE",
};
Amplitude.getInstance().setUserProperties(userProperties);

ユーザープロパティ内の配列

配列をユーザープロパティとして使用できます。配列を直接設定するか、append を使用して配列を生成します。

const colors = ["rose", "gold"];
const numbers = [4, 5];
const identify = new Identify();
identify
  .set("colors", colors)
  .append("ab-tests", "campaign_a")
  .append("existing_list", numbers);
Amplitude.getInstance().identify(identify);

追加する

appendは、ユーザープロパティ配列に1つまたは複数の値を追加します。 ユーザープロパティに値がまだ設定されていない場合、SDKは新しい値を追加する前にそのプロパティを空のリストに初期化します。ユーザープロパティにリスト以外の値がすでに存在する場合、SDK はそれをリストに変換し、新しい値を追加します。

const array = ["some_string", 56];
const identify = new Identify();
identify.append("ab-tests", "new-user-test");
Amplitude.getInstance().identify(identify);

プレインサート

preInsertは、値がユーザープロパティにまだ存在していない場合に、ユーザープロパティに1つまたは複数の値を追加します。 事前挿入とは、指定されたリストの先頭に値を挿入することを意味します。 ユーザープロパティに値がまだ設定されていない場合、SDKは新しい値を事前に挿入する前にユーザープロパティを空のリストに初期化します。ユーザープロパティに既存の値がある場合、これはno-opになります。

const array = ["some_string", 56];
const identify = new Identify();
identify.preInsert("ab-tests", "new-user-test");
Amplitude.getInstance().identify(identify);

挿入後

postInsertは、値がユーザープロパティにまだ存在していない場合に、ユーザープロパティに1つまたは複数の値を追加します。 ポスト挿入とは、指定されたリストの最後に値を挿入することを意味します。 ユーザープロパティに値がまだ設定されていない場合、SDKは新しい値を事後挿入する前にそのプロパティを空のリストに初期化します。ユーザープロパティに既存の値がある場合、これはno-opになります。

const array = ["some_string", 56];
const identify = new Identify();
identify.postInsert("ab-tests", "new-user-test");
Amplitude.getInstance().identify(identify);

ユーザープロパティを削除する

clearUserPropertiesは現在のユーザーのすべてのユーザープロパティを消去します。

Amplitude.getInstance().clearUserProperties();

削除する

removeは、値がユーザープロパティに存在する場合に、そのユーザープロパティから1つまたは複数の値を削除します。その項目がユーザープロパティに存在しない場合、何も起こりません。

const array = ["some_string", 56];
const identify = new Identify();
identify.remove("ab-tests", "new-user-test").remove("some_list", array);
Amplitude.getInstance().identify(identify);

unset

unset ユーザープロパティの設定を解除および削除します。

const identify = new Identify();
identify.unset("karma").unset("gender");
Amplitude.getInstance().identify(identify);

収益の追跡

Amplitudeはユーザーが生み出した収益を追跡できます。 Amplitudeは、AmplitudeのイベントセグメンテーションとレベニューLTVチャートで使用される特別なフィールドを持つ個別の収益オブジェクトを通じて収益を追跡します。

これにより、Amplitudeはプラットフォーム内の収益関連データを自動的に表示できます。 収益オブジェクトは、以下の特別なプロパティとeventPropertiesフィールドを通じて、ユーザー定義のプロパティをサポートしています。

価格は負の値にすることもできます。これは、損失した収益を追跡するのに役立ちます。

type RevenueProperties = {
  price: number;
  productId?: string;
  quantity?: number;
  revenueType?: string;
  receipt?: string;
  receiptSignature?: string;
  eventProperties?: PropertiesObject;
};

const userProperties = {
    price: 100;
    productId: "123";
    quantity: 2;
    revenueType: "productRevenue";
    receipt: "11111";
    receiptSignature: "signature";
    eventProperties: {
        "KAY": "VALUE",
      "OTHER_KEY": "OTHER_VALUE"
    };
}
Amplitude.getInstance().logRevenue(userProperties);

グループユーザープロパティ

Group Identify API を使用して、特定のグループのプロパティを設定または更新します。次の点に留意してください。

• 更新は将来のイベントにのみ影響を与え、過去のイベントを更新することはありません。
• 最大5つの固有のグループタイプと合計10のグループを追跡できます。

このgroupIdentifyメソッドは、グループタイプの文字列パラメータ、グループ名のオブジェクトパラメータ、およびIdentifyオブジェクトを受け入れ、グループに適用します。

const identify = new Identify();
identify.set("gender", "female").set("age", 20);
Amplitude.getInstance().groupIdentify("groupType", "groupValue", identify);

ユーザーセッション

セッションとは、ユーザーがアプリをフォアグラウンドに置いている期間のことです。 同じセッション内で記録されたイベントは、同じsession_idを共有します。

SDKはセッションを自動的に処理するため、startSession()またはendSession()などのAPIを手動で呼び出す必要はありません。 Amplitudeはイベントをセッションごとにグループ化します。

セッションは、開始時刻と終了時刻を持つユーザーのアクティビティの単一期間を表します。 SDK ごとにセッションを追跡する方法が異なります。これはプラットフォームの要件によって異なります。

ユーザーのセッションの開始と終了に対応するセッション開始と終了イベントを自動的に記録するかどうかを決定できます。

//Enable automatically log start and end session events
Amplitude.getInstance().trackingSessionEvents(true);
//Disable automatically log start and end session events
Amplitude.getInstance().trackingSessionEvents(false);

カスタムユーザーIDを設定する

アプリに独自のログインシステムがあり、ユーザーを追跡したい場合は、setUserIdいつでも呼び出してください。

Amplitude.getInstance().setUserId("test_user_id");

高度なトピック

COPPA制御

IDFA、IDFV、都市、IPアドレス、位置情報の追跡に関するCOPPA(児童オンラインプライバシー保護法)の制限をすべて一度に有効または無効にできます。

13 歳未満の子供から情報を求めるアプリは、COPPA に準拠している必要があります。

// Enable COPPA Control
Amplitude.instance().enableCoppaControl();
// Disable COPPA Control
Amplitude.instance().disableCoppaControl();

ユーザーを追跡から除外する

ユーザーは、トラッキングを完全にオプトアウトしたい場合があります。これはイベントも閲覧履歴の記録も残らないことを意味します。setOptOutは、特定のユーザーからのプライバシー保護リクエストに応える手段を提供します。

//Disables instrumentation
Amplitude.getInstance().setOptOut(true);
//Enables instrumentation
Amplitude.getInstance().setOptOut(false);

動的な設定

React Native SDKを使用すると、ユーザーは動的設定を使用するようにアプリを設定できます。この機能は、アプリユーザーの所在地に基づいて最適なサーバー URL を自動的に検出します。

• 独自のプロキシサーバーを持ち、setServerUrlAPIを使用している場合は、動的設定を使用しないでください。
• 中国本土にユーザーがいる場合、Amplitudeでは動的設定を使用することを推奨します。
• デフォルトでは、この機能はオフになっています。 使用するには、明示的に有効にする必要があります。
• デフォルトでは、この機能はAmplitudeの米国サーバーのサーバーURLを返します。 AmplitudeのEUサーバーにデータを送信する必要がある場合は、setServerZoneを使用してEUゾーンに設定してください。

Amplitude.getInstance().setUseDynamicConfig(true);

トラブルシューティング

古いバージョンのReactNativeを使用していて、iOSで問題が発生していますか？

Amplitudeは、0.61以上のバージョンのReactNativeをサポートしています。以下は、ReactNative 0.71でのセットアッププロセスです。詳細については、互換性マトリックスを参照してください。

1. Swiftセットアップ(Xcode)。
   • Xcodeで[project-name].xcodeprojファイルを開きます。
   • ファイルナビゲータでプロジェクト名を右クリックし、「新規ファイル」を選択して「Swift」を選択します。Xcodeは、ブリッジングヘッダーファイルを作成するように求めるメッセージを表示します。これはRN0.61でSwiftをサポートするために必要です。
   • この修正のソース：https://stackoverflow.com/a/54586937。
2. Podfileの変更。
   • iOS 10以降をターゲットにしていることを確認してください。
   • use_modular_headers!をPodfileの先頭にグローバルに追加します。
   • :use_modular_headers => falseを使用して、DoubleConversion、Glog、Follyのモジュール式ヘッダーを無効にします。