> ## Documentation Index
> Fetch the complete documentation index at: https://developers.hubspot.jp/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 訪問者の識別

export const SupportedProducts = ({marketing, sales, service, cms, marketingLevel, salesLevel, serviceLevel, cmsLevel}) => {
  const translations = {
    header: "サポートされる製品",
    description: "次のいずれかの製品またはそれ以上が必要です。",
    productNames: {
      marketing: "Marketing Hub",
      sales: "Sales Hub",
      service: "Service Hub",
      cms: "Content Hub"
    },
    tiers: {
      free: "無料ツール",
      starter: "Starter",
      professional: "Professional",
      enterprise: "Enterprise"
    }
  };
  const translateTier = tier => {
    if (!tier) return '';
    const lowerTier = tier.toLowerCase();
    return translations.tiers[lowerTier] || tier;
  };
  const products = [{
    name: marketing ? translations.productNames.marketing : '',
    level: translateTier(marketingLevel),
    icon: "https://mintlify-assets.b-cdn.net/Icons/marketing-bolt.svg",
    alt: "Marketing Hub"
  }, {
    name: sales ? translations.productNames.sales : '',
    level: translateTier(salesLevel),
    icon: "https://mintlify-assets.b-cdn.net/Icons/sales-star.svg",
    alt: "Sales Hub"
  }, {
    name: service ? translations.productNames.service : '',
    level: translateTier(serviceLevel),
    icon: "https://mintlify-assets.b-cdn.net/Icons/service-heart.svg",
    alt: "Service Hub"
  }, {
    name: cms ? translations.productNames.cms : '',
    level: translateTier(cmsLevel),
    icon: "https://mintlify-assets.b-cdn.net/Icons/content-play.svg",
    alt: "Content Hub"
  }].filter(product => product.name && product.level);
  if (products.length === 0) return null;
  return <div>
      <div className="text-sm mb-2">{translations.description}</div>
      <div className={`grid ${products.length === 1 ? 'grid-cols-1' : 'grid-cols-2'} gap-1.5`}>
        {products.map((product, index) => <div key={index} style={{
    display: 'flex',
    alignItems: 'center'
  }}>
            <img src={product.icon} alt={product.alt} className="w-3.5 h-3.5 mr-1.5 mt-2.5 mb-2.5 flex-shrink-0 align-middle" />
            <span className="font-medium mr-1 text-sm">{product.name} -</span>
            <span className="text-sm">{product.level}</span>
          </div>)}
      </div>
    </div>;
};

export const ScopesList = ({scopes = [], description = "この API には、次のいずれかのスコープが必要です。"}) => {
  if (!scopes || scopes.length === 0) {
    return null;
  }
  const sortedScopes = scopes.sort((a, b) => a.localeCompare(b));
  return <div>
      <div className="text-sm mb-2">{description}</div>
      <div>
        {sortedScopes.map((scope, index) => <div key={index}>
            <code>
              <span className="text-xs">{scope}</span>
            </code>
          </div>)}
      </div>
    </div>;
};

<AccordionGroup>
  <Accordion title="サポートされる製品" defaultOpen="true" icon="cubes">
    <SupportedProducts marketing={true} marketingLevel="professional" sales={true} salesLevel="professional" service={true} serviceLevel="professional" cms={true} cmsLevel="professional" />
  </Accordion>

  <Accordion title="スコープ要件">
    <ScopesList
      scopes={[
  'conversations.visitor_identification.tokens.create'
]}
    />
  </Accordion>
</AccordionGroup>

<RelatedApiLink />

訪問者の識別APIを使用することで、独自の外部認証システムによって認証されたサイト訪問者を識別します。

このAPIから返される識別トークンを使用し、すでに認証された訪問者に関する情報をチャットウィジェットに渡すことで、訪問者が既知のコンタクトとして扱われるようになります。受信トレイのエージェントは誰とやりとりしているかを明確に把握でき、訪問者は複数のデバイス間で過去のスレッド履歴にアクセスできます。

例えば、ログインが必要な独自のWebアプリをホスティングする場合、Webアプリ内のページに、HubSpotのチャットウィジェットが表示されるようにセットアップするかもしれません。Webアプリ内の訪問者は、既に認証されて識別されています。しかし現在のところ、Webアプリで識別されているログイン中の訪問者であっても、そのページ内でチャットをしている訪問者は、コミュニケーションの受信トレイで「不明な訪問者」として表示されます。訪問者の識別APIを使用すると、認証された訪問者の情報を直接チャットウィジェットに渡し、これらの訪問者がコミュニケーション受信トレイで識別されるようにすることができます。

<Warning>
  **注**:

  * 訪問者の識別APIの目的は、訪問者が誰であるかをHubSpotに伝えることです。プラットフォーム内のユーザーを認証する上で、この機能を利用すべきではありません。
  * 訪問者の識別APIを利用するには、ProfessionalまたはEnterpriseエディションのサブスクリプションが必要です。アカウントに適格なサブスクリプションがない場合、APIから`403`エラーレスポンスが返されます。
</Warning>

## 連携フローの例

訪問者の識別機能との連携を使用するには、認証システムを備えた既存のWebアプリケーションが必要です。開始する前に、[非公開アプリ](/apps/legacy-apps/private-apps/overview)がセットアップされていること、また、対象となるProfessionalまたはEnterpriseエディションが、連携しようとしているアカウントで使用されていることを確認してください。

以下に、考えられる連携フローの例を示します。

<Frame>
  <img src="https://developers.hubspot.com/hubfs/Possible%20User%20Identification%20Flow.png" alt="考えられるユーザー識別フロー" />
</Frame>

顧客がシステムにログインして認証されたら、次の手順に従って、ウェブチャットで顧客を識別します。

**1.** フロントエンドで、ウィンドウ上の`hsConversationsSettings`オブジェクトの`loadImmediately`を`false`に設定します。このように設定しないと、識別情報が渡される前にチャットウィジェットが読み込まれる場合があります。詳細については、[以下のチャットウィジェットSDK入門](#chat-widget-sdk-primer)をご確認ください。

* `isConversationsAPIReady`関数の外側で`hsConversationsSettings`プロパティーを設定します。
* さらに、`hsConversationsSettings`を呼び出し前に設定する必要があります。そうしないと、競合状態が発生してウィジェットの読み込みが妨げられる可能性があります。

```js theme={null}
window.hsConversationsSettings = {
  loadImmediately: false,
};
```

**2.** 認証済み訪問者のEメールアドレスを訪問者識別APIに渡すことで、トークンを生成します。この操作は、Webアプリケーションのバックエンドで行う必要があります。リクエストの例については、[エンドポイントのリファレンスドキュメント](/api-reference/conversations-visitor-identification-v3/guide)をご参照ください。

```shell theme={null}
curl --request POST \
  --url 'https://api.hubspot.com/conversations/v3/visitor-identification/tokens/create \
--data '{
  "email": "gob@bluth.com",
  "firstName": "Gob",
  "lastName": "Bluth"
}'
```

<Info>
  以下が該当する場合、提供された氏名は、チャット開始後にHubSpotのコンタクトレコードで設定されます。

  * 訪問者の識別APIによって作成された新しいコンタクトであるｖ名前がまだ分かっていない既存のコンタクトである

  外部システムにはすでに名前の情報がある一方、HubSpotにはまだ存在しない場合、識別された訪問者へのメッセージをパーソナライズするときに役立ちます。これらは任意指定のパラメーターであり、必須ではありません。
</Info>

**3.** ステップ2のトークンを使用して、ウィンドウ上の`hsConversationsSettings`オブジェクトに次のプロパティーを設定します。

```js theme={null}
window.hsConversationsSettings = {
  identificationEmail: "visitor-email@example.com",
  identificationToken: "<TOKEN FROM STEP 1>",
};
```

**4.** ウィジェットを読み込みます。

```js theme={null}
window.HubSpotConversations.widget.load();
```

認証された訪問者のページが読み込まれるたびに、ウィンドウ上の`hsConversationsSettings`オブジェクトにトークンとEメールが設定される必要があります。これらのパラメーターが設定されなくなると、以降のページの読み込み時に、コンテキストは自動的に保持されません。トークンは一時的なもので、12時間後に期限切れになります。トークンが少なくとも12時間に1回更新される場合、トークンをキャッシュして、ページを読み込むたびにトークンを再取得しなくて済むようにできます。

## 連携を確認する

訪問者の識別機能との連携が完了したら、連携が想定通りに機能していることを確認します。以下に示すように、実装に応じて2通りの方法で確認できます。具体的な要件に合わせて、以下の例を調整する必要がある場合があります。

* 1つ以上の公開ページ上および認証システムの背後にチャットウィジェットをすでに追加している場合：

  * チャットウィジェットで訪問者を識別しないページに移動し、コミュニケーションを開始します。
  * HubSpotで受信トレイを開き、受信したチャットが「不明な訪問者」に属していることを確認します。そうでない場合は、非公開のブラウザーウィンドウで次の手順を試してみてください。

    * チャットウィジェットで訪問者識別APIを使用して訪問者を識別するページに移動し、コミュニケーションを開始します。
    * HubSpotで受信トレイを開き、ログインに使用したコンタクトにチャットが属性として正しく結び付けられていることを確認します。正しい関連付けが確認された場合、コンタクトの名前の横に、このコンタクトが訪問者の識別APIで正常に識別されたことを示すバッジが表示されます。

<Frame>
  <img src="https://f.hubspotusercontent00.net/hubfs/53/visitor_identity_badge.png" alt="visitor_identity_badge" />
</Frame>

* 認証システムの背後にあるページにのみチャットウィジェットを追加済みであり、複数のテスト ユーザー アカウントにアクセスできる場合:
  * 最初のテストユーザーとしてHubSpotにログインし、チャットウィジェットが読み込まれるページに移動して、コミュニケーションを開始します。
  * HubSpotからログアウトし、2番目のテストユーザーとして再度ログインします。チャットウィジェットが読み込まれるページに移動し、コミュニケーションを開始します。
  * HubSpotで受信トレイを開き、最初のテストアカウントと2番目のテストアカウントからそれぞれチャットが送信されていて、両方のレコードでコンタクト名の横にバッジが表示されていることを確認します。

<Warning>
  **注**: このAPIで識別された訪問者に関して、HubSpotは`messagesUtk` Cookieをドロップしません。また、Eメールアドレスは既知であることから、HubSpotはEメールキャプチャーの質問をスキップします。`messagesUtk` CookieとEメールキャプチャーはこれらのチャットには適用されないため、訪問者の識別APIを介して識別された訪問者に関しては、チャットフローの関連設定が表示されません。
</Warning>

## チャットウィジェットSDK入門

このAPIは`window.HubSpotConversations`オブジェクトに格納されています。使用可能な全てのメソッドは、このオブジェクトを介して利用されます。このオブジェクトはページ上のHubSpotスクリプトローダーによって自動的に作成されますが、直ちに利用可能にならない場合もあります。APIが初期化されるまでの間、APIへのアクセスを遅延させるには、`window.hsConversationsOnReady`ヘルパーを使用できます。以下に例を示します。

```html theme={null}
<script type="text/javascript">
  function onConversationsAPIReady() {
    console.log(`HubSpot Conversations API: ${window.HubSpotConversations}`);
  }
  /*
    configure window.hsConversationsSettings if needed.
  */
  window.hsConversationsSettings = {};
  /*
   If external API methods are already available, use them.
  */
  if (window.HubSpotConversations) {
    onConversationsAPIReady();
  } else {
    /*
      Otherwise, callbacks can be added to the hsConversationsOnReady on the window object.
      These callbacks will be called once the external API has been initialized.
    */
    window.hsConversationsOnReady = [onConversationsAPIReady];
  }
</script>
```

### SDKリファレンス

`window.hsConversationsOnReady` **配列**

これは、ウィンドウオブジェクトで定義できる任意指定のフィールドです。これを使用すると、ウィジェットが使用可能になったらすぐに実行されるコードを指定できます。APIが初期化されると、この配列の有無が確認され、存在する場合は配列に含まれる一連の関数が実行されます。

```js theme={null}
if (window.HubSpotConversations) {
  console.log("The api is ready already");
} else {
  window.hsConversationsOnReady = [
    () => {
      console.log("Now the api is ready");
    },
  ];
}
```

`hsConversationsSettings` **オブジェクト**

このオブジェクトを使用すると、設定オプションを指定してからウィジェットを初期化できます。訪問者の識別機能を使用するには、次のフィールドを設定する必要があります。

| パラメーター                | タイプ  | 説明                                                                                         | 既定値    |
| --------------------- | ---- | ------------------------------------------------------------------------------------------ | ------ |
| `loadImmediately`     | ブール値 | ウィジェットを暗黙的に読み込むか、それとも`widget.load`メソッドが呼び出されるまで待つか                                         | `true` |
| `identificationToken` | 文字列  | 訪問者識別APIとの連携に使用されます。訪問者の識別API上のトークン生成エンドポイントによって提供されるトークンであり、これを使用してこの訪問者が認証済みであることを証明します。 | `""`   |
| `identificationEmail` | 文字列  | ウィジェットの読み込み中であることがすでに識別された訪問者のメールアドレス。                                                     | `""`   |

```js theme={null}
window.hsConversationsSettings = {
  loadImmediately: false,
  identificationEmail: "visitor-email@example.com",
  identificationToken: "<TOKEN FROM STEP 1>",
};
```

詳しくは[コミュニケーションSDK](https://developers.hubspot.com/docs/api-reference/latest/conversations/chat-configuration/chat-widget-sdk)をご確認ください。