> For the complete documentation index, see [llms.txt](https://docs.wicle.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.wicle.io/integration/others.md).

# 他ツールとの連携

外部ツールからWicleのユーザー詳細を開くURLの作り方と、Sentry・Mixpanelへの連携例を紹介します。

外部ツールにWicleのユーザー詳細URLを保存すると、エラーや問い合わせなどを起点に、そのユーザーの行動を確認できます。このページではURLを使った連携方法と、Sentry・Mixpanelへの追加例を説明します。

{% hint style="info" %}
ユーザーIDを指定する場合は、[ユーザープロファイル](https://docs.wicle.io/data-extension/user-profile.md)で送信した`user_id`と同じ値を使います。リンクの閲覧にはWicleへのログインと、対象プロジェクトへのアクセス権限が必要です。
{% endhint %}

## URL連携 <a href="#url-integration" id="url-integration"></a>

### 基本フォーマット <a href="#basic-format" id="basic-format"></a>

```
https://app.wicle.io/userDetail?apiKey=__YOUR_API_KEY__&userId=__USER_ID__&timestamp=__UNIXTIMESTAMP_MILLS__
```

| パラメーター      | 指定する値                       |
| ----------- | --------------------------- |
| `apiKey`    | 対象プロジェクトの計測タグに使っているAPIキー    |
| `userId`    | Wicleに送信したユーザーID            |
| `timestamp` | 確認したい日時のUNIXタイムスタンプ（ミリ秒）。任意 |

`timestamp`を指定すると、その日時付近のタイムラインを開きます。秒単位のタイムスタンプではなく、JavaScriptの`Date.now()`と同じミリ秒単位で指定してください。

### クライアントサイドでの連携方法 <a href="#block-71ac20efb7ad4fd4b84fa7465ccde836" id="block-71ac20efb7ad4fd4b84fa7465ccde836"></a>

対象ページの計測タグが読み込まれ、`window.__WICLE`が利用できるようになってから呼び出します。URLを取得するだけでは、イベントは送信されません。

| 関数                                         | 開く対象            | 日時       |
| ------------------------------------------ | --------------- | -------- |
| `getAdminUrlForUser(userId)`               | 指定したユーザーID      | 指定なし     |
| `getAdminUrlForUserAndCurrentTime(userId)` | 指定したユーザーID      | 関数を呼んだ時刻 |
| `getAdminUrlForNonUser()`                  | 閲覧中のブラウザのビジターID | 指定なし     |
| `getAdminUrlForNonUserAndCurrentTime()`    | 閲覧中のブラウザのビジターID | 関数を呼んだ時刻 |

ユーザーIDを指定する関数では、IDをURLエンコードして渡します。

```javascript
const userId = encodeURIComponent(String(user.id));
const userUrl = window.__WICLE.getAdminUrlForUser(userId);
const eventUrl = window.__WICLE.getAdminUrlForUserAndCurrentTime(userId);
```

`NonUser`の関数は、ユーザーIDが分からない場合に、現在のブラウザの`visitorId`でURLを生成します。ビジターIDがまだ発行されていない場合は取得できません。

### サーバーサイドでの連携方法 <a href="#block-ede32c04397140238705a70517f9131c" id="block-ede32c04397140238705a70517f9131c"></a>

サーバー側では、対象プロジェクトのAPIキーと送信済みのユーザーIDからURLを組み立てます。各値をURLに適した形式へ変換するため、`URLSearchParams`などを使います。

```javascript
const params = new URLSearchParams({
  apiKey: '__YOUR_API_KEY__',
  userId: String(user.id),
  timestamp: String(Date.now()),
});
const wicleUrl = `https://app.wicle.io/userDetail?${params.toString()}`;
```

日時を指定しない場合は、`timestamp`を省略します。

## 連携の例 <a href="#integration-examples" id="integration-examples"></a>

外部ツールのユーザー属性には日時を指定しないURL、エラーやイベントには発生時刻付きのURLを保存すると、確認する対象を探しやすくなります。以下は、各サービスのJavaScript SDKとWicleの計測タグが利用できるページでの例です。

### Sentry <a href="#sentry" id="sentry"></a>

{% embed url="<https://docs.sentry.io/platforms/javascript/enriching-events/context/>" %}

ユーザー情報にWicleのURLを追加します。

```javascript
Sentry.setUser({
  id: String(user.id),
  wicleUrl: window.__WICLE.getAdminUrlForUser(encodeURIComponent(String(user.id))),
});
```

特定のエラーに、発生時刻付きのURLを追加する場合は、`withScope`でそのエラーに付ける情報を指定します。

```javascript
Sentry.withScope((scope) => {
  scope.setExtra('wicleUrl', window.__WICLE.getAdminUrlForUserAndCurrentTime(encodeURIComponent(String(user.id))));
  Sentry.captureException(error);
});
```

### Mixpanel <a href="#mixpanel" id="mixpanel"></a>

#### ユーザー情報の登録APIでWicleのURLを紐づける <a href="#mixpanel-user-profile" id="mixpanel-user-profile"></a>

[Mixpanelのユーザープロファイル設定](https://docs.mixpanel.com/docs/tracking-methods/sdks/javascript#setting-profile-properties)を使い、ユーザー情報にURLを追加します。

```javascript
mixpanel.identify(String(user.id));
mixpanel.people.set({
  wicleUrl: window.__WICLE.getAdminUrlForUser(encodeURIComponent(String(user.id))),
});
```

#### イベント送信時の拡張データとして付与する <a href="#mixpanel-event-tracking" id="mixpanel-event-tracking"></a>

[Mixpanelのイベント送信](https://docs.mixpanel.com/docs/tracking-methods/sdks/javascript#track-events)で、発生時刻付きのURLをイベントのプロパティとして追加します。

```javascript
mixpanel.track('someEvent', {
  wicleUrl: window.__WICLE.getAdminUrlForUserAndCurrentTime(encodeURIComponent(String(user.id))),
});
```
