Capacitor SDKでオンボーディングイベントを処理する
オンボーディングはSDK v4で非推奨となり、将来のリリースで削除される予定です。 バグ修正や改善は行われません。代わりにフローをご利用ください。オンボーディングはWebView内で動作しますが、フローはデバイス上でネイティブにレンダリングされるため、よりスムーズなアニメーション、一貫したネイティブな外観、高速な読み込み、WebViewランタイムへの依存がなくなります。まずはフローとペイウォールの取得とフローとペイウォールの表示をご覧ください。
ビルダーで設定されたオンボーディングは、アプリが応答できるイベントを生成します。スタンドアロンの画面表示でこれらのイベントを処理するには、setEventHandlers メソッドを使用してください。
始める前に、以下を確認してください：
- オンボーディングを作成済みであること。
- オンボーディングをプレースメントに追加済みであること。
イベントハンドラーの設定
オンボーディングのイベントを処理するには、view.setEventHandlers メソッドを使用します。
try {
const view = await createOnboardingView(onboarding);
view.setEventHandlers({
onAnalytics(event, meta) {
console.log('Analytics event:', event);
},
onClose(actionId, meta) {
console.log('Onboarding closed:', actionId);
return true; // Allow the onboarding to close
},
onCustom(actionId, meta) {
console.log('Custom action:', actionId);
return false; // Don't close the onboarding
},
onPaywall(actionId, meta) {
console.log('Paywall action:', actionId);
view.dismiss().then(() => {
openPaywall(actionId);
});
},
onStateUpdated(action, meta) {
console.log('State updated:', action);
},
onFinishedLoading(meta) {
console.log('Onboarding finished loading');
},
onError(error) {
console.error('Onboarding error:', error);
},
});
await view.present();
} catch (error) {
console.error('Failed to present onboarding:', error);
}イベントの種類
以下のセクションでは、処理できるさまざまなイベントの種類を説明します。
カスタムアクションの処理
ビルダーでは、ボタンにカスタムアクションを追加してIDを割り当てることができます。
その後、このIDをコードで使用し、カスタムアクションとして処理できます。たとえば、ユーザーが Login や Allow notifications などのカスタムボタンをタップすると、ビルダーの Action ID と一致する actionId パラメータを持つイベントハンドラが呼び出されます。“allowNotifications” のような独自のIDを作成できます。
view.setEventHandlers({
onCustom(actionId, meta) {
switch (actionId) {
case 'login':
console.log('Login action triggered');
break;
case 'allow_notifications':
console.log('Allow notifications action triggered');
break;
}
return false; // Don't close the onboarding
},
});イベントの例（クリックして展開）
{
"actionId": "allow_notifications",
"meta": {
"onboardingId": "onboarding_123",
"screenClientId": "profile_screen",
"screenIndex": 0,
"screensTotal": 3
}
}オンボーディングの読み込み完了
オンボーディングの読み込みが完了すると、このイベントがトリガーされます：
view.setEventHandlers({
onFinishedLoading(meta) {
console.log('Onboarding loaded:', meta.onboardingId);
},
});イベントの例（クリックして展開）
{
"meta": {
"onboarding_id": "onboarding_123",
"screen_cid": "welcome_screen",
"screen_index": 0,
"total_screens": 4
}
}オンボーディングを閉じる
ユーザーがCloseアクションが割り当てられたボタンをタップすると、オンボーディングは閉じられたとみなされます。
ユーザーがオンボーディングを閉じたときの処理は、ご自身で実装する必要があります。たとえば、オンボーディング自体の表示を停止する処理などが必要です。
view.setEventHandlers({
onClose(actionId, meta) {
console.log('Onboarding closed:', actionId);
return true; // Allow the onboarding to close
},
});イベントの例（クリックで展開）
{
"action_id": "close_button",
"meta": {
"onboarding_id": "onboarding_123",
"screen_cid": "final_screen",
"screen_index": 3,
"total_screens": 4
}
}ペイウォールを開く
オンボーディング内でペイウォールを開きたい場合は、このイベントを処理してください。ペイウォールを閉じた後に別のペイウォールを開きたい場合は、もっとシンプルな方法があります。クローズアクションを処理して、イベントデータに依存せずにペイウォールを開いてください。
オンボーディングでペイウォールをシームレスに扱う方法は、アクション ID をペイウォールのプレースメント ID と同じにすることです。
iOSでは、一度に画面に表示できるビュー（ペイウォールまたはオンボーディング）は1つだけです。オンボーディングの上にペイウォールを表示した場合、バックグラウンドのオンボーディングをプログラムで操作することはできません。オンボーディングを閉じようとすると、代わりにペイウォールが閉じられ、オンボーディングが残ったままになります。これを防ぐため、ペイウォールを表示する前に必ずオンボーディングビューを閉じてください。
view.setEventHandlers({
onPaywall(actionId, meta) {
// ペイウォールを表示する前にオンボーディングを閉じる
view.dismiss().then(() => {
openPaywall(actionId);
});
},
});
async function openPaywall(placementId: string) {
// ここにペイウォールを開くロジックを実装する
}イベントの例（クリックして展開）
{
"action_id": "premium_offer_1",
"meta": {
"onboarding_id": "onboarding_123",
"screen_cid": "pricing_screen",
"screen_index": 2,
"total_screens": 4
}
}ナビゲーションのトラッキング
オンボーディングフローの実行中にさまざまなナビゲーション関連イベントが発生すると、アナリティクスイベントを受け取ります。
view.setEventHandlers({
onAnalytics(event, meta) {
console.log('Analytics event:', event.type, 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
}
}