React Native SDKでオンボーディングイベントを処理する
ビルダーで設定されたオンボーディングは、アプリが応答できるイベントを生成します。これらのイベントの処理方法は、使用するプレゼンテーション方式によって異なります:
- モーダルプレゼンテーション:すべてのオンボーディングビューのイベントを処理するイベントハンドラーのセットアップが必要
- Reactコンポーネント:ウィジェット内のインラインコールバックパラメーターを通じてイベントを処理
始める前に、以下を確認してください:
- Adapty React Native SDK 3.8.0以降をインストール済みであること。
- オンボーディングを作成済みであること。
- オンボーディングをプレースメントに追加済みであること。
モバイルアプリ内のオンボーディング画面で発生するプロセスを制御・監視するには、イベントハンドラーを実装してください:
Reactコンポーネントでは、AdaptyOnboardingViewコンポーネントの個別のイベントハンドラープロップを通じてイベントを処理します:
function MyOnboarding({ onboarding }) {
const onAnalytics = useCallback<OnboardingEventHandlers['onAnalytics']>((event, meta) => {}, []);
const onClose = useCallback<OnboardingEventHandlers['onClose']>((actionId, meta) => {}, []);
const onCustom = useCallback<OnboardingEventHandlers['onCustom']>((actionId, meta) => {}, []);
const onPaywall = useCallback<OnboardingEventHandlers['onPaywall']>((actionId, meta) => {}, []);
const onStateUpdated = useCallback<OnboardingEventHandlers['onStateUpdated']>((action, meta) => {}, []);
const onFinishedLoading = useCallback<OnboardingEventHandlers['onFinishedLoading']>((meta) => {}, []);
const onError = useCallback<OnboardingEventHandlers['onError']>((error) => {}, []);
return (
<AdaptyOnboardingView
onboarding={onboarding}
style={styles.container}
onAnalytics={onAnalytics}
onClose={onClose}
onCustom={onCustom}
onPaywall={onPaywall}
onStateUpdated={onStateUpdated}
onFinishedLoading={onFinishedLoading}
onError={onError}
/>
);
}
モーダルプレゼンテーションでは、イベントハンドラーメソッドを実装します。
setEventHandlersを複数回呼び出すと、提供したハンドラーが上書きされ、特定のイベントに対するデフォルトと以前に設定したハンドラーの両方が置き換えられます。
const view = await createOnboardingView(onboarding);
const unsubscribe = view.setEventHandlers({
onAnalytics(event, meta) {
// Track analytics events
},
onClose(actionId, meta) {
// Handle close action
view.dismiss();
return true;
},
onCustom(actionId, meta) {
// Handle custom actions
},
onPaywall(actionId, meta) {
// Handle paywall actions
},
onStateUpdated(action, meta) {
// Handle user input updates
},
onFinishedLoading(meta) {
// Onboarding finished loading
},
onError(error) {
// Handle loading errors
},
});
try {
await view.present();
} catch (error) {
// handle the error
}
SDKバージョン3.14未満では、モーダルプレゼンテーションのみサポートされています:
const view = await createOnboardingView(onboarding);
const unsubscribe = view.registerEventHandlers({
onAnalytics(event, meta) {
// Track analytics events
},
onClose(actionId, meta) {
// Handle close action
view.dismiss();
return true;
},
onCustom(actionId, meta) {
// Handle custom actions
},
onPaywall(actionId, meta) {
// Handle paywall actions
},
onStateUpdated(action, meta) {
// Handle user input updates
},
onFinishedLoading(meta) {
// Onboarding finished loading
},
onError(error) {
// Handle loading errors
},
});
try {
await view.present();
} catch (error) {
// handle the error
}
イベントの種類
以下のセクションでは、使用するプレゼンテーション方式に関わらず処理できる各種イベントについて説明します。
カスタムアクションを処理する
ビルダーでボタンにカスタムアクションを追加してIDを割り当てることができます。
このIDをコード内で使用し、カスタムアクションとして処理できます。たとえば、ユーザーがログインや通知を許可などのカスタムボタンをタップすると、ビルダーのAction IDに対応するactionIdパラメーターを持つイベントハンドラーがトリガーされます。「allowNotifications」のような独自のIDを作成できます。
function MyOnboarding({ onboarding }) {
const onCustom = useCallback<OnboardingEventHandlers['onCustom']>((actionId, meta) => {
switch (actionId) {
case 'login':
login();
break;
case 'allow_notifications':
allowNotifications();
break;
}
}, []);
return (
<AdaptyOnboardingView
onboarding={onboarding}
style={styles.container}
onCustom={onCustom}
/>
);
}
const view = await createOnboardingView(onboarding);
const unsubscribe = view.setEventHandlers({
onCustom(actionId, meta) {
switch (actionId) {
case 'login':
login();
break;
case 'allow_notifications':
allowNotifications();
break;
}
},
});
const view = await createOnboardingView(onboarding);
const unsubscribe = view.registerEventHandlers({
onCustom(actionId, meta) {
switch (actionId) {
case 'login':
login();
break;
case 'allow_notifications':
allowNotifications();
break;
}
},
});
イベントの例(クリックして展開)
{
"actionId": "allow_notifications",
"meta": {
"onboardingId": "onboarding_123",
"screenClientId": "profile_screen",
"screenIndex": 0,
"screensTotal": 3
}
}
オンボーディングの読み込み完了
オンボーディングの読み込みが完了すると、このイベントがトリガーされます:
function MyOnboarding({ onboarding }) {
const onFinishedLoading = useCallback<OnboardingEventHandlers['onFinishedLoading']>((meta) => {
console.log('Onboarding loaded:', meta.onboardingId);
}, []);
return (
<AdaptyOnboardingView
onboarding={onboarding}
style={styles.container}
onFinishedLoading={onFinishedLoading}
/>
);
}
const view = await createOnboardingView(onboarding);
const unsubscribe = view.setEventHandlers({
onFinishedLoading(meta) {
console.log('Onboarding loaded:', meta.onboardingId);
},
});
const view = await createOnboardingView(onboarding);
const unsubscribe = view.registerEventHandlers({
onFinishedLoading(meta) {
console.log('Onboarding loaded:', meta.onboardingId);
},
});
イベントの例(クリックして展開)
{
"meta": {
"onboarding_id": "onboarding_123",
"screen_cid": "welcome_screen",
"screen_index": 0,
"total_screens": 4
}
}
オンボーディングを閉じる
ユーザーが閉じるアクションが割り当てられたボタンをタップすると、オンボーディングが閉じられたと判断されます。
ユーザーがオンボーディングを閉じたときの動作は自分で管理する必要があります。たとえば、オンボーディング自体の表示を停止する処理が必要です。
function MyOnboarding({ onboarding, navigation }) {
const onClose = useCallback<OnboardingEventHandlers['onClose']>((actionId, meta) => {
navigation.goBack();
}, [navigation]);
return (
<AdaptyOnboardingView
onboarding={onboarding}
style={styles.container}
onClose={onClose}
/>
);
}
const view = await createOnboardingView(onboarding);
const unsubscribe = view.setEventHandlers({
onClose(actionId, meta) {
await view.dismiss();
return true;
},
});
const view = await createOnboardingView(onboarding);
const unsubscribe = view.registerEventHandlers({
onClose(actionId, meta) {
await view.dismiss();
return true;
},
});
イベントの例(クリックして展開)
{
"action_id": "close_button",
"meta": {
"onboarding_id": "onboarding_123",
"screen_cid": "final_screen",
"screen_index": 3,
"total_screens": 4
}
}
ペイウォールを開く
オンボーディング内でペイウォールを開きたい場合は、このイベントを処理してください。オンボーディングを閉じた後にペイウォールを開きたい場合は、より簡単な方法があります。閉じるアクションを処理してイベントデータに依存せずにペイウォールを開いてください。
オンボーディングでペイウォールを扱う最もシームレスな方法は、アクションIDをペイウォールのプレースメントIDと同じにすることです。
function MyOnboarding({ onboarding }) {
const onPaywall = useCallback<OnboardingEventHandlers['onPaywall']>((actionId, meta) => {
openPaywall(actionId);
}, []);
return (
<AdaptyOnboardingView
onboarding={onboarding}
style={styles.container}
onPaywall={onPaywall}
/>
);
}
const openPaywall = async (placementId) => {
// Implement your paywall opening logic here
};
iOSでは、一度に表示できるビュー(ペイウォールまたはオンボーディング)は1つのみです。オンボーディングの上にペイウォールを表示した場合、バックグラウンドのオンボーディングをプログラムで制御することはできません。オンボーディングを閉じようとすると、代わりにペイウォールが閉じられ、オンボーディングが表示されたままになります。これを避けるために、ペイウォールを表示する前に常にオンボーディングビューを閉じてください。
const view = await createOnboardingView(onboarding);
const unsubscribe = view.setEventHandlers({
onPaywall(actionId, meta) {
view.dismiss().then(() => {
openPaywall(actionId);
});
},
});
const openPaywall = async (placementId) => {
// Implement your paywall opening logic here
};
iOSでは、一度に表示できるビュー(ペイウォールまたはオンボーディング)は1つのみです。オンボーディングの上にペイウォールを表示した場合、バックグラウンドのオンボーディングをプログラムで制御することはできません。オンボーディングを閉じようとすると、代わりにペイウォールが閉じられ、オンボーディングが表示されたままになります。これを避けるために、ペイウォールを表示する前に常にオンボーディングビューを閉じてください。
const view = await createOnboardingView(onboarding);
const unsubscribe = view.registerEventHandlers({
onPaywall(actionId, meta) {
view.dismiss().then(() => {
openPaywall(actionId);
});
},
});
const openPaywall = async (placementId) => {
// Implement your paywall opening logic here
};
イベントの例(クリックして展開)
{
"action_id": "premium_offer_1",
"meta": {
"onboarding_id": "onboarding_123",
"screen_cid": "pricing_screen",
"screen_index": 2,
"total_screens": 4
}
}
ナビゲーションの追跡
オンボーディングフロー中にナビゲーション関連のイベントが発生すると、アナリティクスイベントを受け取ります:
function MyOnboarding({ onboarding }) {
const onAnalytics = useCallback<OnboardingEventHandlers['onAnalytics']>((event, meta) => {
trackEvent(event.name, meta.onboardingId);
}, []);
return (
<AdaptyOnboardingView
onboarding={onboarding}
style={styles.container}
onAnalytics={onAnalytics}
/>
);
}
const view = await createOnboardingView(onboarding);
const unsubscribe = view.setEventHandlers({
onAnalytics(event, meta) {
trackEvent(event.name, meta.onboardingId);
},
});
const view = await createOnboardingView(onboarding);
const unsubscribe = view.registerEventHandlers({
onAnalytics(event, meta) {
trackEvent(event.name, meta.onboardingId);
},
});
eventオブジェクトは以下のいずれかのタイプになります:
| タイプ | 説明 |
|---|
onboardingStarted | オンボーディングの読み込みが完了したとき |
screenPresented | いずれかの画面が表示されたとき |
screenCompleted | 画面が完了したとき。オプションのelementId(完了した要素の識別子)とオプションのreply(ユーザーからの回答)を含みます。ユーザーが画面を抜けるアクションを実行したときにトリガーされます。 |
secondScreenPresented | 2番目の画面が表示されたとき |
userEmailCollected | 入力フィールドからユーザーのメールアドレスが収集されたときにトリガーされます |
onboardingCompleted | ユーザーがfinal IDを持つ画面に到達したときにトリガーされます。このイベントが必要な場合は、最後の画面にfinal IDを割り当ててください。 |
unknown | 認識されないイベントタイプの場合。name(未知のイベントの名前)とmeta(追加のメタデータ)を含みます |
各イベントには以下のmeta情報が含まれます:
| フィールド | 説明 |
|---|
onboardingId | オンボーディングフローの一意の識別子 |
screenClientId | 現在の画面の識別子 |
screenIndex | フロー内の現在の画面の位置 |
screensTotal | フロー内の画面の総数 |
イベントの例(クリックして展開)
// onboardingStarted
{
"name": "onboarding_started",
"meta": {
"onboarding_id": "onboarding_123",
"screen_cid": "welcome_screen",
"screen_index": 0,
"total_screens": 4
}
}
// screenPresented
{
"name": "screen_presented",
"meta": {
"onboarding_id": "onboarding_123",
"screen_cid": "interests_screen",
"screen_index": 2,
"total_screens": 4
}
}
// screenCompleted
{
"name": "screen_completed",
"meta": {
"onboarding_id": "onboarding_123",
"screen_cid": "profile_screen",
"screen_index": 1,
"total_screens": 4
},
"params": {
"element_id": "profile_form",
"reply": "success"
}
}
// secondScreenPresented
{
"name": "second_screen_presented",
"meta": {
"onboarding_id": "onboarding_123",
"screen_cid": "profile_screen",
"screen_index": 1,
"total_screens": 4
}
}
// userEmailCollected
{
"name": "user_email_collected",
"meta": {
"onboarding_id": "onboarding_123",
"screen_cid": "profile_screen",
"screen_index": 1,
"total_screens": 4
}
}
// onboardingCompleted
{
"name": "onboarding_completed",
"meta": {
"onboarding_id": "onboarding_123",
"screen_cid": "final_screen",
"screen_index": 3,
"total_screens": 4
}
}