---
title: "Capacitor SDKでオンボーディングイベントを処理する"
description: "Adaptyを使用してCapacitorでオンボーディング関連のイベントを処理します。"
---

ビルダーで設定されたオンボーディングは、アプリが応答できるイベントを生成します。スタンドアロン画面の表示でこれらのイベントを処理するには、`setEventHandlers` メソッドを使用してください。

始める前に、以下を確認してください：

1. [オンボーディングを作成](create-onboarding)済みであること。
2. オンボーディングを[プレースメント](placements)に追加済みであること。

## イベントハンドラーの設定 \{#set-up-event-handlers\}

オンボーディングのイベントを処理するには、`view.setEventHandlers` メソッドを使用します：

```typescript showLineNumbers

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);
}
```

## イベントの種類 \{#event-types\}

以下のセクションでは、処理できるさまざまなイベントの種類を説明します。

### カスタムアクションの処理 \{#handle-custom-actions\}

ビルダーでボタンに **custom** アクションを追加し、IDを割り当てることができます。

  <img src="/assets/shared/img/ios-events-1.webp"
  style={{
    border: '1px solid #727272', /* border width and color */
    width: '700px', /* image width */
    display: 'block', /* for alignment */
    margin: '0 auto' /* center alignment */
  }}
/>

このIDをコード内で使用し、カスタムアクションとして処理できます。たとえば、ユーザーが **Login** や **Allow notifications** などのカスタムボタンをタップすると、ビルダーの **Action ID** と一致する `actionId` パラメーターを持つイベントハンドラーがトリガーされます。"allowNotifications" のような独自のIDを作成できます。

```typescript showLineNumbers
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
  },
});
```

<Details>
<summary>イベントの例（クリックして展開）</summary>

```json
{
  "actionId": "allow_notifications",
  "meta": {
    "onboardingId": "onboarding_123",
    "screenClientId": "profile_screen",
    "screenIndex": 0,
    "screensTotal": 3
  }
}
```
</Details>

### オンボーディングの読み込み完了 \{#finishing-loading-onboarding\}

オンボーディングの読み込みが完了すると、このイベントがトリガーされます：

```typescript showLineNumbers
view.setEventHandlers({
  onFinishedLoading(meta) {
    console.log('Onboarding loaded:', meta.onboardingId);
  },
});
```

<Details>
<summary>イベントの例（クリックして展開）</summary>

```json
{
    "meta": {
        "onboarding_id": "onboarding_123",
        "screen_cid": "welcome_screen",
        "screen_index": 0,
        "total_screens": 4
    }
}
```
</Details>

### オンボーディングを閉じる \{#closing-onboarding\}

ユーザーが **Close** アクションが割り当てられたボタンをタップすると、オンボーディングは閉じられたと見なされます。

  <img src="/assets/shared/img/ios-events-2.webp"
  style={{
    border: '1px solid #727272', /* border width and color */
    width: '700px', /* image width */
    display: 'block', /* for alignment */
    margin: '0 auto' /* center alignment */
  }}
/>

:::important
ユーザーがオンボーディングを閉じたときに何が起こるかを自分で管理する必要があります。たとえば、オンボーディング自体の表示を停止する必要があります。
:::

```typescript showLineNumbers
view.setEventHandlers({
  onClose(actionId, meta) {
    console.log('Onboarding closed:', actionId);
    return true; // Allow the onboarding to close
  },
});
```

<Details>
<summary>イベントの例（クリックして展開）</summary>

```json
{
  "action_id": "close_button",
  "meta": {
    "onboarding_id": "onboarding_123",
    "screen_cid": "final_screen",
    "screen_index": 3,
    "total_screens": 4
  }
}
```
</Details>

### ペイウォールを開く \{#opening-a-paywall\}

:::tip
オンボーディング内でペイウォールを開きたい場合は、このイベントを処理してください。オンボーディングが閉じた後にペイウォールを開きたい場合は、クローズアクションを処理してイベントデータに依存せずにペイウォールを開く、よりシンプルな方法があります。
:::

オンボーディングでペイウォールを扱う最もシームレスな方法は、アクションIDをペイウォールのプレースメントIDと同じにすることです。

iOSでは、一度に1つのビュー（ペイウォールまたはオンボーディング）のみ画面に表示できることに注意してください。オンボーディングの上にペイウォールを表示する場合、バックグラウンドのオンボーディングをプログラムで操作することはできません。オンボーディングを閉じようとすると、代わりにペイウォールが閉じられ、オンボーディングが残ったままになります。これを避けるために、ペイウォールを表示する前に必ずオンボーディングビューを閉じてください。

```typescript showLineNumbers
view.setEventHandlers({
  onPaywall(actionId, meta) {
    // Dismiss onboarding before presenting paywall
    view.dismiss().then(() => {
      openPaywall(actionId);
    });
  },
});

async function openPaywall(placementId: string) {
  // Implement your paywall opening logic here
}
```

<Details>
<summary>イベントの例（クリックして展開）</summary>

```json
{
    "action_id": "premium_offer_1",
    "meta": {
        "onboarding_id": "onboarding_123",
        "screen_cid": "pricing_screen",
        "screen_index": 2,
        "total_screens": 4
    }
}
```
</Details>

### ナビゲーションのトラッキング \{#tracking-navigation\}

オンボーディングフロー中にさまざまなナビゲーション関連イベントが発生すると、アナリティクスイベントを受け取ります：

```typescript showLineNumbers
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を割り当ててください](design-onboarding)。 |
| `unknown` | 認識されないイベントタイプの場合。`name`（不明なイベントの名前）と `meta`（追加のメタデータ）を含む |

各イベントには以下の `meta` 情報が含まれます：

| フィールド | 説明 |
|------------|-------------|
| `onboardingId` | オンボーディングフローの一意の識別子 |
| `screenClientId` | 現在の画面の識別子 |
| `screenIndex` | フロー内での現在の画面の位置 |
| `screensTotal` | フロー内の画面の総数 |

<Details>
<summary>イベントの例（クリックして展開）</summary>

```javascript
// 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
    }
}
```
</Details>