エンドユーザー更新APIの統合

Download as PDF

概要

エンドユーザー更新APIは、顧客向けのAPIを呼び出し、特定のエンドユーザーの属性を更新できる統合です。 これを使用することで、エンドポイント（URL）にコールバックを送信できるあらゆるSaaSサービスからサーバー側の更新呼び出しを送信できるようになります。

これにより、WalkMeのエンドユーザーオブジェクトでリアルタイムの更新情報を受け取ることが可能になります。統合の設定では、WalkMeのエンドユーザーオブジェクトに保存される任意のペイロード（許可リスト）からインポートしたいフィールドを特定することができ、これらは、後でInsights、レポート、セグメンテーションでのフィルタリングに利用可能です。

ユースケース

• 新しいエンドユーザーが登録された際に、WalkMeのエンドユーザーオブジェクトをリアルタイムに更新。
• エンドユーザーが無料ユーザーから有料ユーザーにアップグレードした場合、WalkMeのエンドユーザーオブジェクトをリアルタイムで更新し、このデータをコンテンツのセグメンテーション評価に利用できるようにする。
• 顧客が解約した場合、WalkMeのエンドユーザーオブジェクトをリアルタイムで更新。
• 顧客の年間経常収益（ARR）が100万ドルを超え、顧客を「プレミアム顧客」と定義できるようになった際、WalkMeのエンドユーザーオブジェクトを更新するようにウェブフックを設定。

エンドユーザー更新API統合を作成

ステップ1 - 新しいエンドユーザー更新API統合を作成する

1. Insightsに移動します
2. [Integrations（統合）]タブに移動します（メニューの左下）
3. [API to WalkMe]をクリックします - 統合ウィザードのSSVが開きます

ステップ2 - 統合を定義する

1. 統合に名前を付ける - これは、EditorのセグメンテーションセンターのルールエンジンとInsightsに表示される名前であるため、意味のある名前を付けてください。
2. ユーザー識別プロパティ を入力 - WalkMeで特定されたエンドユーザーIDを保持するフィールドを入力します。例えば、選択したエンドユーザーの識別方法がエンドユーザーのメールアドレスを含む変数である場合、入力するフィールドは、エンドユーザーのメールアドレスを保持するペイロードJSON内のフィールドである必要があります。 ペイロードがJSONオブジェクトのフォーマットの場合は、ドットで区切られた名前（<オブジェクト名>.<フィールド名>）を使用します。
3. インポートするプロパティを入力する - WalkMeにインポートするペイロードJSONのフィールドとそのタイプを入力します。 これらのフィールドは、セグメンテーション、Insightsでのフィルタリングやレポートで利用できるようになります。 ペイロードがJSONオブジェクトのフォーマットの場合は、ドットで区切られた名前（<オブジェクト名>.<フィールド名>）を使用します。サポートされているタイプは、文字列、数値、日付（YY-MM-DDのフォーマット）です。
4. [Continue（続行）]をクリックします

ステップ3 - 統合エンドポイントを取得してテストする

1. 統合では、APIリクエスト送信先のエンドポイントが表示されるようになりました。
   

   curl -L -X POST 'https://api.walkme.com/public/v1/user/data' --header 'Content-Type: application/json' --header 'Authorization: Bearer <access-token>' --data-raw '{ "token": "c865ab9ec9ffd1fbbe18a452951329bdd3e814484086bc0068da807208062c40", "data": [ { "properties.ID": "name@company.com", "field1": "value", "field2": 123, "nested": { "field": 456 } } ] }'

2. このエンドポイントを、WalkMeへのリクエスト送信に使用しているサービスにコピーします。

ステップ4 - 更新APIエンドポイントに更新リクエストを送信する

エンドユーザーアップデートAPIは、WalkMeのPublic APIを介してアクセスできます。 使用するには、2つの呼び出しが必要です。

1. 認証トークンを取得する呼び出し（https://developer.walkme.com/reference#getting-started-with-your-api-1を参照）
2. 抽出されたトークン認証を使用して、ステップ3で取得したエンドポイントにPOSTリクエストを送信します。 リクエストのペイロードは、設定された統合に対応するものである必要があります（以下の例を参照）。
   1. リクエストの本文は、「token」と「data」プロパティを持つ有効なJSONオブジェクトでなければなりません。
   2. 「token」プロパティには、統合センターでエンドポイントが作成されたときに取得した値を含める必要があります。 「access-token」と混同してはいけません。
   3. 「data」プロパティは、ユーザーIDフィールドおよび少なくとももう1つの値を持つフィールドが含まれるJSONオブジェクトの配列です（「NULL」は有効な値ではありません）。 フィールド名は、統合ポイントを設定する際に定義された統合スキーマと一致する必要があります。

エンドユーザー更新APIをセグメンテーションに使用

1. 連動が設定されたら、空のパブリッシュを実行して、エディタのインポートされたフィールドに基づいてセグメント化できます。
2. WalkMe Editorで、[Manage Segments（セグメントの管理）]メニューに移動します。
3. 新しいセグメントを作成するか、既存のセグメントを編集します。
4. ルールエンジンで、「user attributes（ユーザー属性）」のグループを選択、統合名（「ステップ2 - 統合を定義する」で設定）を選択して、セグメント化したいフィールドをリストから選択します。
5. 条件を定義します（表示される演算子は、「ステップ2 - 統合を定義する」で挿入したフィールドのタイプによって定義されることにご注意ください）。
6. [Done（完了）]をクリックします。

エンドユーザー更新APIをInsightsでデータのフィルタリングに使用

1. Insightsで、新しいフィルターを作成するか、既存のフィルターを更新します。
2. [USER（ユーザー）]を選択、「ステップ2 - 統合を定義する」でインポートしたフィールドをクリックします。 複数の統合から複数のフィールドで名前が同じになる場合があるため、リストの各フィールドの横にある説明テキストに注目してください。
3. 条件を定義します（表示される演算子は、「ステップ2 - 統合を定義する」で挿入したフィールドのタイプによって定義されることにご注意ください）。
4. [Save Filter（フィルターを保存）]をクリックします。

ベストプラクティス

1. 統合を変更すると、変更はすぐに更新されます。
2. エンドユーザー更新APIが呼び出されると、エンドユーザーオブジェクトは直ちに更新されます。 条件はWMが読み込まれるたびに評価されるため、エンドユーザーがこの呼び出しを送信しているウェブフックに接続されているボタン（アカウントの更新ボタンなど）をクリックした場合、条件は次のWMの読み込み（次のページまたは更新）でのみ再度評価されることにご留意ください。
3. 属性は少なめに - WalkMeに統合する属性の総数に注意してください。全統合で使用できる属性の総数は、合計100です。
4. 他の受信統合とは異なり、エンドユーザー更新APIは、APIが呼び出されたとき、およびAPIが呼び出された特定のエンドユーザーに対してのみ更新されることを強調することが重要です。
5. 事前にすべてのエンドユーザーの属性を一括設定したい場合は、Incomingインテグレーション - CSVアップロードを使用できます。
   この場合、2つの統合は2つの異なる属性を設定することになりますのでご注意ください。
   1. 100の属性という制限は、すべての統合（APIと受信一括統合の両方）を対象としているため、両方にすべてのフィールドがある場合、実際の制限は15に減少します。
   2. セグメンテーションのルール定義では、2つのルールを使って構築し、ルール間で「OR」の関係を使用する必要があります。 例：
      Incomingインテグレーション顧客タイプ = 'paying' OR APIインテグレーション顧客タイプ = 'paying'.

プロセス例

以下は、エンドユーザーのメールアドレスをIDとしたWalkMeシステムの顧客ステータスとタイプ属性を更新する方法の実例です。

ステップ1 - 新しいエンドユーザー更新API統合を作成する

1. Insightsに移動します
2. [Integrations（統合）]タブに移動します（メニューの左下）
3. [API to WalkMe]をクリックします - 統合ウィザードが開きます

ステップ2 - 統合を定義する

1. 統合に名前を付ける -「顧客属性の更新」
2. ユーザー識別プロパティを入力 - 使用しているWalkMeの識別方法はエンドユーザーのメールアドレスを返す変数で、ペイロードには「Email」というプロパティの下にエンドユーザーのメールアドレスが含まれるため、「Email」を選択します。
3. インポートするプロパティを入力 - ペイロードには「Type」と「Status」の2つのインポートしたいプロパティが含まれています。 これらの名前を「Customer_Type」と「Customer_Status」に変更して、セグメンテーションルールエンジンとInsightsに表示される属性名にします。
   
   これらのプロパティはどちらも文字列タイプの値を含むため、「Property Type」には「String（文字列）」を選択します。
4. [Continue（続行）]をクリックします

ステップ3 - 統合エンドポイントを取得する

1. 統合では、APIリクエスト送信先のエンドポイントが表示されるようになりました。
2. [Copy（コピー）]アイコンをクリックして、WalkMeへのリクエスト送信に使用するサービスにこのエンドポイントをコピーします。

ステップ4 - 2つの呼び出しを行うことで更新APIエンドポイントに更新リクエストを送信する

1. 認証トークンを取得します（「開発者ハブ」の「APIの利用を開始する」を参照）。POST呼び出しを送信します。https://api.walkme.com/accounts/connect/tokenAuthorization Type = Basic Auth（ユーザー名とパスワードは、アカウント用に受信したユーザー名とパスワードでなければなりません（「前提条件」を参照））Token = <ステップ4.1で取得したアクセストークン>本文：

   "{["grant_type" : "client_credentials"]}" 次の応答でアクセス トークンが受信されます："access_token": "eyJhbGciOiJSUzI1NiIsImtpZNURDNTY1NkU4RDc4NEUiLCJ0eXAiOiJKV1QiLCJ4NXQiOiJhYzRpVXJXLUNZSDNHUjY3LVYzRlpXNk5lRTQifQ.eyJuYmYiOjE1Nzc2Mjk1MzYsImV4cCI6MTU3NzcxNTkzNiwiaXNzIjoiaHR0cHM6Ly9hcGkud2Fsa21lcWEuY29tL2FjY291bnRzIiwiYXVkIjpbImh0dHBzOi8vYXBpLndhbGttZXFhLmNvbS9hY2NvdW50cy9yZXNvdXJjZXMiLCJXYWxrTWUgcHVibGljIl0sImNsaWVudF9pZCI6IjdkNjhiYTUwMGQwYTExZTk4MWI4MDJlZGRhNjMiLCJqdGkiOiI4NmQyZmE1Mi00YjkxLTQyZjUtOTgxMS0wZDUxOWM4YTI1ZGMiLCJqd2siOiIzYzM4eVVwbGVrSFJHWEFoVTVKajl3Z0JBYXBBdFoyQSIsInNjb3BlIjpbImxhbmd1YWdlczpyZWFkIiwibGFuZ3VhZ2VzOndyaXRlIiwicm9sZXM6cmVhZCIsInVzZXJzOnJlYWQiLCJ1c2Vyczp3cml0ZSJdfQ.Ufmo0cR6L9LfAfFl8tE-ZwQmFS5db0IRmXeRtDw2RZ88n1yV7wJ-bHKkZcIObv90achf2-3MhSdELZPH_YJQLz858Y79szfyUi5kraX2dHfA3U7UujjuL3qEUZMK0NR5JC37RIm-tvApOrbzl0Vc4aFKSF5Ae8pBOd2zfdsTvMkczI928AFJ-ieO9-U8Pl3vrYLNjaG-WzRE111ckQzzWMf1F2svdx9VRxxLOfm8TtVatuvcAS4uQFW1XKVVAn7VLMyGJDoM6Q03UXhUsyWwtQ78wilqY2xNEM0iQS9iuDfwp5dZEzw8nrIepKBoskBGXTac8z6QQXlHfpI3Gu64YyIQc2rDyyoFFZvPNOYbV5REI6rIKpYMWvTmDXyvnON84_Ojiq0HW-ikQmMSyvHWQpS0mXDiw4x3vkwOxUIaYwQJpCILGcqgomLr7XfoqRtPz25kG2ezneCuP0WpEGsT0K2I29m0pI4HwChXOY4UeRvbTpmCWBXnfYeE8RKNClnpFGv6Vl13hvVIu42IVTXy6w8dbngf9p0L9XzwaDRXnb6apDNow49gzVidjdSw1pe2A_INGbyyNeE-mxm-rIOTeqqY5q8MK62wOeF14W3KjztHhD0q7sMhaTrXHyk3pucK6LtDsdVSFWIpGKwI6L1yBNaujDOqxuhMzkblfDB7eXUCI6IjY5Q0UyMjUyQjVCRTA5ODFGNzE5MUVCQkY5", "expires_in": 86400, "token_type": "Bearer", "scope": "languages:read languages:write roles:read users:read users:write"}

2. 抽出されたトークンを使用して、ステップ3で取得した統合エンドポイントにPOSTリクエストを送信します。