SDKをインストールする

ユーザーを特定する

イベントを追跡する

属性を追跡

ユーザーをグループ化する

フィードバックを送信

JavaScript SDK

SDKをインストールする

以下がSpecificタグです。あなたのウェブサイトまたはウェブアプリの各ページのコードに、Specificがユーザーを追跡したい場所にコピーして貼り付けてください。<head>要素の直後に貼り付けてください。各ページに複数のSpecificタグを追加しないでください。

最後の行でWORKSPACE_IDを必ず交換してください。インテグレーションのセクションで見つけることができます。

<script type="text/javascript">
  (function(l, e, a, p) {
    if (window.Specific) return
    window.Specific = function() {
      S._queue.push(arguments)
    }
    var S = window.Specific
    S.appId = a
    S._queue = []
    a = l.createElement('script')
    a.async = 1
    a.src = e + '?id=' + S.appId
    p = l.getElementsByTagName('script')[0]
    p.parentNode.insertBefore(a, p)
  })(document, 'https://cdn.specific.app/bundle.js', 'WORKSPACE_ID')
</script>

ユーザーを特定する

誰が何を言ったのか知りたい場合は、これは重要です。そうでなければ、すべての回答は匿名のままになります。

ユーザーが当社のSDKを使用したページを訪れると、ターゲットを絞ったアンケートを可能にする一意の訪問者IDを受け取ります。ただし、ユーザーの訪問者IDが貴社システム内の一意のユーザーIDと一致するまで、ユーザーは認証されません。

すでにシステムでIDを使用している場合は、一貫したターゲティングのためにプラットフォーム間でIDを同期し、調査が繰り返されるのを防ぐことをお勧めします。

IDの要件：

ユニーク: 2人のユーザーが同じIDを共有することはありません。
マッピング可能: IDはあなたの内部システムにリンクします。
静的: IDは時間が経っても同じままです。

ユーザーIDを設定

ログイン時にsetUserIdを使用して、ユーザーの識別子（最大256文字）を割り当てます。この機能は複数回呼び出すことができ、セッション間でのユーザー識別の一貫性を確保します。

Specific('setUserId', 'USER_ID');

ログアウト

ユーザーがあなたのサイトや製品からログアウトした際には、必ず私たちのシステムからもログアウトさせてください。これにより、新しい操作が誤って他のユーザーに紐付けされることを防ぎます。認証されていないユーザーに対してこれを使用する場合、新しいIDが作成され、あなたのユーザー制限に個別にカウントされることに注意してください。

Specific('ログアウトユーザー');

イベントを追跡してアンケートをトリガーする

イベントは、製品内でのユーザーの行動に基づいてアンケートを起動したり、特定のユーザーをターゲットにしたりするために使用されます。イベントを追跡することで、アンケートが適切なタイミングで適切なオーディエンスに表示されることを保証できます。

イベントの種類

私たちのプラットフォームは、アンケートをトリガーおよびフィルタリングするための2種類のイベントをサポートしています。

ノーコードイベント: これらのイベントは、コードベースにアクセスすることなくチームメンバーによって設定でき、迅速な更新や実験に最適です。ノーコードイベントは、後で直感的なインターフェースを使用して設定することができます。
コードイベント: これらのイベントは、開発者がコードベースに直接トラッキングを実装する必要があります。非常にカスタマイズ可能で、詳細なターゲッティングや行動分析のための追加のプロパティを含めることができます。

ノーコードイベントの設定方法

ノーコードイベントは、アプリケーションのコードを変更することなく、イベントインターフェースを通じて直接設定できます。これにより、技術的な知識がないチームメンバーでも、アンケートをトリガーするためのイベントを迅速に定義し管理することが可能になります。

コードイベントの実装

コードイベントを追跡するためには、アプリケーションに以下のスニペットを使用できます。これにより、イベントがバックグラウンドで追跡されます。

Specific('イベント', 'イベント名');

イベントを即座にトリガーして調査を開始したい場合（例：ユーザーがボタンをクリックした後にモーダルを開く）、この拡張スニペットを使用してください。サーバーの応答を待たずに瞬時にフィードバックを提供します。

Specific('イベント', 'イベント名', { loadingPlacement: '中央', autoFocus: true });

ユーザーをターゲットにするための属性を追跡する

属性を使用すると、ユーザーに関する情報を増やし、調査をより効果的にターゲットにするという2つの重要な目標を達成できます。

ユーザーに関するデータを追加することで、誰が各回答を提供したのかを確認でき、会話を匿名ではなく識別可能にします。

ターゲティングに関しては、属性を使用するとフォーカスを絞ることができます。例えば、特定のユーザーセグメント、パワーユーザーや特定の国のユーザーにのみアンケートを表示することができます。また、属性を使用することで、アンケートの回答をフィルターし、分析することが容易になります。

名前、メールアドレス

ユーザーの名前とメールアドレスを設定するには、setName および setEmail を使用します。

Specific('setName', 'ジョン・ドウ');
Specific('setEmail', 'john@example.com');

カスタム属性

使用 setAttributes または setAttribute を使用して、ユーザーの国やパワーユーザーかどうかなどのカスタム属性を追加します。

// 複数の属性を設定
Specific('setAttributes', {
  power_user: true,
  country: "US"
});

// 単一の属性を設定
Specific('setAttribute', 'country', 'US');

言語

製品のUIが複数の言語をサポートしている場合、ユーザーの母国語で調査を行うことができます。setLanguageを使用し、ISO 639-1言語コードを使って（言語コードの一覧参照）ユーザーの希望する言語を設定してください。

Specific('setLanguage', 'ja');

バックエンドから属性を設定する

バックエンドから属性を設定する必要がある多くのユースケースがあります。それも可能です！ここでは、文字列、数値、そしてブール値の例を挙げます。

あなたのPERSONAL_API_KEYは、APIセクションの設定で生成できます。また、インテグレーションUIからWORKSPACE_IDを取得できます。# コメントを忘れずに削除してください。

curl -X POST 'https://wapi.specific.app/api/v1/user' \
-H 'authorization: PERSONAL_API_KEY' \
-H 'x-app: WORKSPACE_ID' \
-H 'Content-Type: application/json' \
-d '{
  "id": "123456789",            # 必須: ユーザーの一意のID
  "name": "John Doe",           # 任意: ユーザーの名前
  "email": "john@example.com",  # 任意: ユーザーのメールアドレス
  "group": {                    # 任意: グループの詳細
    "id": "4242424242424242",   # 任意: グループID
    "name": "Acme Inc."         # 任意: グループの名前
  },
  "attrs": [                    # 任意: ユーザー属性
    {
      "key": "company_size",    # 任意の属性キー
      "value": 1000             # 例の値
    },
    {
      "key": "active",          # 任意の属性キー
      "value": true             # 例の値
    },
    {
      "key": "subscription_plan", # 任意の属性キー
      "value": "Free"             # 例の値
    }
  ]
}'

ユーザーをグループ化（会社、ワークスペースなど）

ユーザーを意味のあるグループに整理するには、setGroup 関数を使用します。例えば、会社やワークスペース（例：Figmaのワークスペース）です。この関数は、ユーザーを特定のグループ—会社IDやワークスペースIDのようなもの—にログイン時に割り当て、セッション間での一貫したグループ追跡を保証します。各グループIDは最大で256文字まで可能です。

主要な推奨事項:

配置: このコードスニペットはアプリケーション内のどこにでも追加できますが、通常はユーザー登録やログイン時に setUserId 関数の近くに追加されます。
一意性: GROUP_ID はユニークな識別子で、理想的にはデータベースからのワークスペースまたは会社のIDであることを確認してください。
属性: 会社名および追加属性 (例: subscription_plan、company_size) を含めて、フィルタリングおよびレポート機能を強化してください。
制限: ユーザーは一度に一つのグループにしか所属できません。

ユーザーをグループ化することで、会話を分析し、レポートをフィルタリングし、アンケートをより効果的にターゲットできます。

Specific('setGroup', 'GROUP_ID', {
    name: 'アクメ株式会社',
    attributes: {
        'サブスクリプションプラン': '無料',
        '会社の規模': 1000,
    }
});

バックエンドから属性を設定する

バックエンドから属性を設定する必要がある場合も、簡単にできますよ！

curl -X POST 'https://wapi.specific.app/api/v1/group' \
-H 'authorization: PERSONAL_API_KEY' \
-H 'x-app: WORKSPACE_ID' \
-H 'Content-Type: application/json' \
-d '{
  "id": "4242424242424242",         # 必須: ユニークなグループID
  "name": "Acme Inc.",              # 任意: グループ名
  "attrs": [                        # 任意: グループ属性
    {
      "key": "active",              # 任意の属性キー
      "value": true                 # 例: 値 (グループはアクティブ)
    },
    {
      "key": "company_size",        # 任意の属性キー
      "value": 1000                 # 例: 値 (従業員数)
    },
    {
      "key": "subscription_plan",   # 任意の属性キー
      "value": "Free"               # 例: 値 (サブスクリプションタイプ)
    }
  ]
}'

私たちの公開APIを使用して、さらに多くのことができます。詳細は、APIドキュメントでご覧ください。