Advisor [開発者向けプレビュー版]

「アドバイザー」機能は、Identity Insightsのリクエストで要求された、および／または利用可能なインサイトに基づいて分析を行い、アドバイスや評価結果を返します。

Advisorは、さまざまなユースケースや業界に適用可能な4つの静的モデルに基づいています：

合成ID：カスタマージャーニーにおける合成IDのリスクを評価するために設計されたモデル。
なりすまし：カスタマージャーニーにおけるなりすましリスクを評価するために設計されたモデル。
アカウント乗っ取り：カスタマージャーニーにおけるアカウント乗っ取りのリスクを評価するために設計されたモデル。
カスタマーエクスペリエンス：カスタマージャーニーにおけるカスタマーエクスペリエンスの指標を評価するために設計されたモデル。

これらのモデルは、短期的から中期的に「Identity Insights」で現在利用可能なシグナルとよく合致するレベルの複雑さと、多様なユースケースを備えています。各モデルには、推奨されるインサイト、属性値に基づくシグナルの定義、および属性の範囲がセットとして含まれています。

リクエストに「Advisor」のインサイトを含めると、レスポンスには各モデルについて以下の情報が追加で含まれます：

おすすめのインサイト：そのモデルにおすすめのインサイトをまとめた配列。
シグナル：カスタマージャーニーの関連する側面を評価するために使用される、特定の属性とその対応する値または値の範囲。シグナルは、Identity Insights が取得したデータ内の有意義なパターンや異常を浮き彫りにすることで、リスク、ユーザー体験、またはコンプライアンスの評価に役立ちます。
指標：
- completeness_ratio: 推奨されたインサイトの総数に対する、利用可能な（欠損のない）インサイトの割合。0から1の間の値で表される。
- positive_ratio: 各アドバイス種別の比率（以下を除く） MISSED_INSIGHT)
- warning_ratio: 各アドバイス種別の比率（以下を除く） MISSED_INSIGHT)
- negative_ratio: 各アドバイス種別の比率（以下を除く） MISSED_INSIGHT)
- weighted_ratio: 各アドバイス種別ごとの加重比率（以下を除く） MISSED_INSIGHT)
モデルからのアドバイス：
- completeness: 以下の内容に基づいたアドバイス completeness_ratio メートル法。
- worst_case: その助言は、あるとすれば最悪の助言だ
- weighted: 肯定的なシグナル、否定的なシグナル、および不明なシグナルを考慮に入れ、関連するシグナルを総合的に評価した上で、全体的な推奨事項を提示してください。

前提条件

Identity Insights を使用するには、アカウントが正しく設定されていることを確認する必要があります。はじめにのガイドを参照されたい：

アカウントの作成
Identity Insights API で使用する Vonage アプリケーションの作成、
利用可能なさまざまな環境と、それらを使用するためのアカウントの設定方法、
また、Dashboard Getting Started UIを使用して、コードを書かずにAPIを使用する方法も紹介します。

このガイドでは、cURL を使用して Advisor Insight をプログラムから操作する方法について説明します。

Identity Insights API は、複数の地域のエンドポイントから利用できる。本ガイドの例では EU エンドポイントを使用していますが、全リストは以下を参照してください。技術詳細.

APIを呼び出す

Identity Insights API の認証は、コンパクトで自己完結型の JSON トークンである JWT を介して行われます。JWT を生成するには、当社のオンラインジェネレーターあるいは Vonage CLI.JWTを生成するには、アプリケーションIDと秘密鍵が必要です。JWTを取得したら、APIにリクエストを送信できます。

この例では、AdvisorおよびSIMスワップインサイトに対するcURLリクエストを示しています。これは、過去240時間以内にSIMスワップが発生したかどうかを確認し、そのインサイトからの分析結果を取得するためのものです。

curl -X POST https://api-eu.vonage.com/identity-insights/v1/requests  \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "14040000000",
    "purpose": "FraudPreventionAndDetection",
    "insights": {
      "sim_swap": {
        "period": 240
      },
      "advisor": {}
    }
  }'

その後、APIはSIMスワップインサイトからの応答を分析し、評価を行った上で、それに基づいてアドバイスを提供します：

{
  "request_id":"c2cc7a65-9b10-493f-9c0a-1c86751a91c4",
  "insights":{
    "sim_swap":{
      "latest_sim_swap_at":"2024-07-08T09:30:27.504Z",
      "is_swapped":true,
      "status":{
        "code":"OK",
        "message":"Success"
      }
    },
    "advisor":{
      "synthetic_identity":{
        "recommended_insights":[
          "format",
          "original_carrier"
        ],
        "signals":[
          {
            "attribute":"format",
            "advice":"MISSED_INSIGHT",
            "assessment":"Insight missed - This Insight is recommended to evaluate advisor synthetic_identity model."
          },
          {
            "attribute":"original_carrier",
            "advice":"MISSED_INSIGHT",
            "assessment":"Insight missed - This Insight is recommended to evaluate advisor synthetic_identity model."
          }
        ],
        "metrics":{
          "completeness_ratio":0,
          "positive_ratio":0,
          "warning_ratio":0,
          "negative_ratio":0,
          "weighted_ratio":0
        },
        "model_advice":{
          "completeness":"LOW",
          "worst_case":"WARNING",
          "weighted":"WARNING"
        }
      },
      "impersonation":{
        "recommended_insights":[
          "format",
          "original_carrier",
          "current_carrier",
          "subscriber_match"
        ],
        "signals":[
          {
            "attribute":"format",
            "advice":"MISSED_INSIGHT",
            "assessment":"Insight missed - This Insight is recommended to evaluate advisor impersonation model."
          },
          {
            "attribute":"original_carrier",
            "advice":"MISSED_INSIGHT",
            "assessment":"Insight missed - This Insight is recommended to evaluate advisor impersonation model."
          },
          {
            "attribute":"current_carrier",
            "advice":"MISSED_INSIGHT",
            "assessment":"Insight missed - This Insight is recommended to evaluate advisor impersonation model."
          },
          {
            "attribute":"subscriber_match",
            "advice":"MISSED_INSIGHT",
            "assessment":"Insight missed - This Insight is recommended to evaluate advisor impersonation model."
          }
        ],
        "metrics":{
          "completeness_ratio":0,
          "positive_ratio":0,
          "warning_ratio":0,
          "negative_ratio":0,
          "weighted_ratio":0
        },
        "model_advice":{
          "completeness":"LOW",
          "worst_case":"WARNING",
          "weighted":"WARNING"
        }
      },
      "account_take_over":{
        "recommended_insights":[
          "format",
          "sim_swap"
        ],
        "signals":[
          {
            "attribute":"format",
            "advice":"MISSED_INSIGHT",
            "assessment":"Insight missed - This Insight is recommended to evaluate advisor account_take_over model."
          },
          {
            "attribute":"sim_swap",
            "advice":"NEGATIVE",
            "assessment":"A SIM swap represents a high risk of account takeover."
          }
        ],
        "metrics":{
          "completeness_ratio":0.5,
          "positive_ratio":0,
          "warning_ratio":0,
          "negative_ratio":1,
          "weighted_ratio":0
        },
        "model_advice":{
          "completeness":"MEDIUM",
          "worst_case":"NEGATIVE",
          "weighted":"NEGATIVE"
        }
      },
      "customer_experience":{
        "recommended_insights":[
          "format",
          "current_carrier"
        ],
        "signals":[
          {
            "attribute":"format",
            "advice":"MISSED_INSIGHT",
            "assessment":"Insight missed - This Insight is recommended to evaluate advisor customer_experience model."
          },
          {
            "attribute":"current_carrier",
            "advice":"MISSED_INSIGHT",
            "assessment":"Insight missed - This Insight is recommended to evaluate advisor customer_experience model."
          }
        ],
        "metrics":{
          "completeness_ratio":0,
          "positive_ratio":0,
          "warning_ratio":0,
          "negative_ratio":0,
          "weighted_ratio":0
        },
        "model_advice":{
          "completeness":"LOW",
          "worst_case":"WARNING",
          "weighted":"WARNING"
        }
      },
      "status":{
        "code":"OK",
        "message":"Success."
      }
    }
  }
}

さらに読む

Identity Insights API の詳細については、以下を参照してください。 APIリファレンス.
ご不明な点がございましたら、下記までお問い合わせください。 VonageコミュニティSlack.