はじめに

1. パッケージをインストール

   npm

   npm i @capgo/capacitor-crisp

   pnpm

   pnpm add @capgo/capacitor-crisp

   yarn

   yarn add @capgo/capacitor-crisp

   bun

   bun add @capgo/capacitor-crisp

2. ネイティブプロジェクトと同期

   npm

   npx cap sync

   pnpm

   pnpm cap sync

   yarn

   yarn cap sync

   bun

   bunx cap sync

3. Crisp Website IDを取得

   • crisp.chatでサインアップ
   • ウェブサイト/プロジェクトを作成
   • Settings > Setup InstructionsでWebsite IDを見つける

基本的な使い方

プラグインをインポートし、Website IDで設定します:

import { CapacitorCrisp } from '@capgo/capacitor-crisp';

// Website IDでCrispを設定
const configureCrisp = async () => {
  await CapacitorCrisp.configure({
    websiteID: 'YOUR_WEBSITE_ID'
  });
};

// チャットを開く
const openChat = async () => {
  await CapacitorCrisp.openMessenger();
};

// ユーザー情報を設定
const setUserInfo = async () => {
  await CapacitorCrisp.setUser({
    email: 'user@example.com',
    nickname: 'John Doe',
    phone: '+1234567890',
    avatar: 'https://example.com/avatar.jpg'
  });
};

// ユーザーセッションをリセット (ログアウト)
const logout = async () => {
  await CapacitorCrisp.resetChatSession();
};

APIリファレンス

configure(options)

Website IDとオプション設定でCrispを設定します。

interface ConfigureOptions {
  websiteID: string;
  locale?: string; // 例: 'en', 'fr', 'es'
  tokenID?: string; // 認証済みセッション用
}

await CapacitorCrisp.configure({
  websiteID: 'YOUR_WEBSITE_ID',
  locale: 'en'
});

openMessenger()

Crispチャットインターフェースを開きます。

await CapacitorCrisp.openMessenger();

setUser(options)

チャットセッションのユーザー情報を設定します。

interface UserOptions {
  email?: string;
  nickname?: string;
  phone?: string;
  avatar?: string;
}

await CapacitorCrisp.setUser({
  email: 'user@example.com',
  nickname: 'John Doe'
});

setUserCompany(options)

ビジネスユーザーの会社情報を設定します。

interface CompanyOptions {
  name: string;
  url?: string;
  description?: string;
  employment?: {
    title?: string;
    role?: string;
  };
  geolocation?: {
    city?: string;
    country?: string;
  };
}

await CapacitorCrisp.setUserCompany({
  name: 'Acme Corp',
  url: 'https://acme.com',
  employment: {
    title: 'CEO',
    role: 'Leadership'
  }
});

pushEvent(options)

ユーザーアクションを追跡するカスタムイベントを送信します。

interface EventOptions {
  name: string;
  color?: 'red' | 'orange' | 'yellow' | 'green' | 'blue' | 'purple' | 'pink' | 'brown' | 'grey' | 'black';
  data?: { [key: string]: any };
}

await CapacitorCrisp.pushEvent({
  name: 'checkout_completed',
  color: 'green',
  data: {
    price: 99.99,
    currency: 'USD'
  }
});

setSessionSegment(segment)

チャットセッションを分類するセグメントを設定します。

await CapacitorCrisp.setSessionSegment('premium_customer');

resetChatSession()

現在のチャットセッションをリセットします (ログアウト時に便利)。

await CapacitorCrisp.resetChatSession();

高度な機能

カスタムユーザーデータ

// 複数のカスタムデータフィールドを設定
await CapacitorCrisp.setSessionData({
  key: 'plan',
  value: 'premium'
});

await CapacitorCrisp.setSessionData({
  key: 'signup_date',
  value: '2024-01-15'
});

メッセージプリセット

チャット入力欄に事前入力されたメッセージを設定:

await CapacitorCrisp.setMessageText(
  "Hello, I need help with my order #12345"
);

チャットの可用性

チャットウィジェットが利用可能な時間を制御:

// 一時的にチャットを非表示
await CapacitorCrisp.setTokenID('user_token_12345');

完全な例

import { CapacitorCrisp } from '@capgo/capacitor-crisp';

export class ChatService {
  async initialize() {
    // Crispを設定
    await CapacitorCrisp.configure({
      websiteID: 'YOUR_WEBSITE_ID',
      locale: 'en'
    });
  }

  async loginUser(user: any) {
    // ユーザー情報を設定
    await CapacitorCrisp.setUser({
      email: user.email,
      nickname: user.name,
      phone: user.phone,
      avatar: user.avatarUrl
    });

    // カスタムデータを設定
    await CapacitorCrisp.setSessionData({
      key: 'user_id',
      value: user.id
    });

    await CapacitorCrisp.setSessionData({
      key: 'account_type',
      value: user.accountType
    });

    // セグメントを設定
    if (user.isPremium) {
      await CapacitorCrisp.setSessionSegment('premium');
    }

    // ログインイベントを追跡
    await CapacitorCrisp.pushEvent({
      name: 'user_login',
      color: 'blue',
      data: {
        method: 'email'
      }
    });
  }

  async openSupport(context?: string) {
    if (context) {
      await CapacitorCrisp.setMessageText(
        `I need help with: ${context}`
      );
    }

    await CapacitorCrisp.openMessenger();
  }

  async logout() {
    await CapacitorCrisp.resetChatSession();
  }
}

スタイルとカスタマイズ

Crispはアプリのテーマに自動的に適応しますが、Crispダッシュボードでさらにカスタマイズできます:

1. Crispダッシュボードに移動
2. Settings > Website Settings > Chatbox & Email Settingsに移動
3. 色、位置、動作をカスタマイズ

ベストプラクティス

1. 早期初期化 即座に利用できるよう、アプリ初期化時にCrispを設定:

   import { App } from '@capacitor/app';
   
   App.addListener('appStateChange', async ({ isActive }) => {
     if (isActive) {
       await CapacitorCrisp.configure({
         websiteID: 'YOUR_WEBSITE_ID'
       });
     }
   });

2. ユーザーコンテキストの設定 より良いサポートのため、利用可能な場合は常にユーザー情報を提供:

   if (user.isAuthenticated) {
     await CapacitorCrisp.setUser({
       email: user.email,
       nickname: user.name
     });
   }

3. 重要なイベントの追跡 サポートエージェントにコンテキストを提供するためにイベントを使用:

   await CapacitorCrisp.pushEvent({
     name: 'error_occurred',
     color: 'red',
     data: {
       error: error.message,
       screen: 'checkout'
     }
   });

4. 適切なログアウト処理 ユーザーがログアウトする際は必ずセッションをリセット:

   async logout() {
     await CapacitorCrisp.resetChatSession();
     // その他のログアウトロジック
   }

プラットフォーム注意事項

iOS

• iOS 10.0+が必要
• ネイティブCrisp iOS SDKを使用
• プッシュ通知をサポート (Crispダッシュボードで設定)

Android

• Android 5.0 (API 21)+が必要
• ネイティブCrisp Android SDKを使用
• Material Design準拠

Web

• Crisp JavaScript SDKにフォールバック
• ネイティブプラットフォームと完全な機能パリティ