AIアクティベーション用の関数を作成する

このガイドでは、リアルタイムアクティベーションのために外部AIモデルをTealium関数に統合する方法について説明します。モデルエンドポイントに安全に接続し、イベントデータと訪問データを使用してAI予測を呼び出し、モデル出力で訪問プロファイルを豊かにします。非同期応答と一般的な統合問題についても取り上げます。

Tealium関数またはAIコネクタを使用するタイミングについての情報は、AIコネクタとTealium関数を参照してください。

動作原理

機能を使用して、顧客離脱リスク、詐欺検出、傾向スコアリング、次の最適なアクションの推奨などのタスクのために外部AIモデルを呼び出します。機能はイベントデータと訪問プロファイル属性を収集し、ペイロードを構築し、モデルエンドポイントに送信し、予測を受け取り、アクティベーションのために訪問プロファイルを更新します。

リアルタイムモデル推論とアクティベーションのためのデータフローには、以下のステップが含まれます：

1. 顧客アクション: ユーザーがアクションを実行します（例：商品を見る、カートに追加する、フォームを送信する）。
2. 機能トリガー: イベントまたは訪問機能が構成されたトリガーに基づいて発火し、予測（スコア、分類、推奨）を返します。
3. イベントを収集する: 機能は予測データをtrack()メソッドを通じてTealium Collectに送信します。
4. エンリッチメント処理: 構成されたエンリッチメントが予測値を訪問プロファイル属性に書き込みます。
5. ダウンストリームアクティベーション: オーディエンスが評価し、更新されたプロファイル属性に基づいてコネクタが発火します。

機能は直接訪問プロファイルを変更することはできないため、予測はTealium Collectを通じてプロファイルに書き込まれる必要があります。

track()メソッドはイベントをTealium Collectに送信します。これらのイベント属性値を訪問プロファイル属性に書き込むためにエンリッチメントを構成する必要があります。

機能の種類

リアルタイム推論とアクティベーションのために外部AIモデルを呼び出すことで、以下のような複数の利点があります：

• 訪問の行動からリアルタイムで顧客離脱リスクを検出します。
• 高リスク訪問を特定することでリテンションキャンペーンのターゲティングを改善します。
• AIに基づく予測を使用してセグメンテーションによるパーソナライズされた体験をサポートします。
• モデル駆動の洞察によってプロファイルをエンリッチすることで、ダウンストリームアクティベーションの精度を向上させます。
• 高スループットデータストリームを処理してタイムリーな分析と対応を行います。
• マーケティング、アナリティクス、コンプライアンスのワークフローのデータ品質を向上させます。

前提条件

AIモデルを呼び出すための機能を作成する前に、以下のものを確保してください：

• REST APIエンドポイントにデプロイされた訓練済みのMLモデル、例えばSnowflake Cortex、Databricks Model Serving、AWS SageMaker、Google Vertex AI、Azure ML、Hugging Face Inference Endpoints、または任意のHTTPSエンドポイント。
• モデルエンドポイントのAPI認証情報、例えばAPIキー、ベアラートークン、またはJWT。
• プロファイルリージョンのTealium IPアドレスをデータクラウドの許可リストに追加します。詳細については、許可するTealium IPアドレスを参照してください。
• モデルが期待するリクエストペイロードスキーマ。
• モデルが返すレスポンスペイロードスキーマ。

AIに基づく顧客離脱リスク分析のための主要コンポーネント

• データ変換機能
  受信イベントデータを評価し、正規表現を適用して顧客離脱リスクに関連する行動を特定します。

• 派生属性
  イベントデータから顧客離脱リスクスコアを計算します。この値は各イベントに対して機能によって構成されます。

• AudienceStreamイベントフィルター
  顧客離脱リスクスコアを使用してイベントをフィルタリングします。高リスクのイベントのみが訪問プロファイルを豊かにします。

• イベントフィード
  高リスクとフラグ付けされたイベントをコネクタ、保存、または他の機能によるさらなる処理のためにストリーミングします。

• 外部モデル呼び出し機能
  イベントまたはプロファイルデータを外部AIモデルエンドポイントに送信して高度な顧客離脱予測を行います。

• エンリッチメント
  AIモデルの予測を訪問プロファイル属性に書き込み、アクティベーションとセグメンテーションのために使用します。

要件

このソリューションを実装するためには、以下が必要です：

• Tealiumの要件
  • AudienceStreamが有効になっていること
  • Tealiumの機能が有効になっていること
  • track()イベントを受信するための構成済みデータソース
  • 予測属性を訪問プロファイルに書き込むためのエンリッチメント
• モデルエンドポイントの要件
  • HTTPSプロトコルを使用すること
  • 10秒以内に応答すること。リアルタイムパーソナライゼーションのためには、応答時間が500ミリ秒未満であることを推奨します。
  • ベアラートークン、APIキー、またはヘッダーベースの認証を使用すること
  • JSON形式で応答すること。

ステップ1: 機能を作成する

イベント機能または訪問機能を使用してAIアクティベーションロジックを実装できます。使用例とスコアリング時の利用可能なデータに最も適した機能タイプを選択します。

コード参照

プラットフォーム固有の注意点

以下のコード例は一般的なREST APIパターンを示しています。実際の実装はプラットフォームによって異なります：

プラットフォームのAPIドキュメントを参照して、リクエスト/レスポンス形式と認証要件について確認してください。

イベント関数の例

次の例は、イベント関数から外部モデルAPIを呼び出す方法を示しています。ペイロードの構造とレスポンスの解析を、あなたのモデルのAPIに合わせて調整してください。

activate(async ({ event, helper }) => {
  // 1. イベントデータから特徴ペイロードを組み立てる
  // これをモデルの期待する入力形式に合わせて調整してください
  const payload = {
    product_id: event.data.udo.product_id,
    category: event.data.udo.product_category,
    price: event.data.udo.product_price
  };
  // 2. モデルAPIを呼び出す
  const response = await fetch(
    helper.getGlobalVariable('MODEL_ENDPOINT_URL'),
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer ' + helper.getAuth('model_api_token'),
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(payload)
    }
  );
  if (!response.ok) {
    console.error('Model API error:', response.status);
    return;
  }
  const result = await response.json();
  // 3. Tealium Collectに予測を送信する
  // 属性名をモデルのレスポンスに合わせて調整してください
  track({
    tealium_event: 'model_prediction',
    prediction_score: result.score,
    prediction_label: result.label
  }, {
    tealium_account: event.account,
    tealium_profile: event.profile,
    tealium_datasource: helper.getGlobalVariable('DATASOURCE_KEY')
  });
});

ビジター関数の例

ビジター関数は蓄積されたプロファイルデータにアクセスしてスコアリングが可能ですが、event オブジェクトにはアクセスできませんので、account、profile、および datasource の値にはグローバル変数を使用する必要があります。

activate(async ({ visitor, visit, helper }) => {
  // ビジタープロファイル属性からペイロードを組み立てる
  const payload = {
    lifetime_value: visitor.metrics.lifetime_value,
    purchase_count: visitor.metrics.purchase_count,
    days_since_last_purchase: visitor.metrics.days_since_last_purchase,
    loyalty_tier: visitor.properties.loyalty_tier
  };
  const response = await fetch(
    helper.getGlobalVariable('MODEL_ENDPOINT_URL'),
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer ' + helper.getAuth('model_api_token'),
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(payload)
    }
  );
  if (!response.ok) {
    console.error('Model API error:', response.status);
    return;
  }
  const result = await response.json();
  // ビジター関数では、ルーティングにグローバル変数を使用する
  // イベントが正しいプロファイルに紐付けられるようにvisitor_idを含める
  track({
    tealium_event: 'churn_prediction',
    tealium_visitor_id: visitor.properties.visitor_id,
    churn_score: result.churn_probability,
    churn_risk_tier: result.risk_tier
  }, {
    tealium_account: helper.getGlobalVariable('TEALIUM_ACCOUNT'),
    tealium_profile: helper.getGlobalVariable('TEALIUM_PROFILE'),
    tealium_datasource: helper.getGlobalVariable('DATASOURCE_KEY')
  });
});

モデル応答の遅延処理

モデル推論に10秒以上かかる場合は、非同期パターンを使用します。関数はリクエストを送信してすぐに終了します。処理が完了すると、モデルがTealiumにコールバックします。

1. 関数はビジターデータとコールバックURLをモデルエンドポイントに送信します
2. モデルエンドポイントは直ちに202 Acceptedを返します
3. 関数は終了します（タイムアウトなし）
4. モデルは非同期で推論を完了します
5. モデルはTealiumのHTTP APIに予測をPOSTします
6. エンリッチメントは予測をビジタープロファイルに書き込みます

モデルコールバック用のHTTP APIデータソースを作成する

モデルコールバックを受信するためのHTTP APIデータソースを作成します。詳細については、データソースを作成するを参照してください。

非同期関数コード

次の関数コードを使用します：

activate(async ({ visitor, visit, helper }) => {
  const payload = {
    visitor_id: visitor.properties.visitor_id,
    lifetime_value: visitor.metrics.lifetime_value,
    purchase_count: visitor.metrics.purchase_count,
    callback_url: helper.getGlobalVariable('TEALIUM_CALLBACK_URL'),
    callback_datasource: helper.getGlobalVariable('DATASOURCE_KEY')
  };
  // 応答を待たずに発火 - レスポンスを待たない
  fetch(
    helper.getGlobalVariable('MODEL_ENDPOINT_URL'),
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer ' + helper.getAuth('model_api_token'),
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(payload)
    }
  ).catch(error => console.error('Request failed:', error.message));
  // 関数はすぐに終了 - モデルが準備ができたときにコールバックする
});

モデルコールバックペイロード

モデルエンドポイントは、推論が完了するとTealium HTTP APIにPOSTする必要があります：

POST https://collect.tealiumiq.com/event?tealium_account={account}&tealium_profile={profile}&tealium_datasource={datasource_key}

{
  "tealium_event": "model_prediction_complete",
  "tealium_visitor_id": "original_visitor_id_from_request",
  "churn_score": 0.82,
  "churn_risk_tier": "high",
  "model_version": "v2.1"
}

tealium_visitor_idを含めることで、予測が正しいビジタープロファイルに紐付けられることが保証されます。ステップ3で説明されているように、これらの属性をプロファイルに書き込むためにエンリッチメントを構成します。

ステップ2: MLプラットフォームの認証情報を構成する

モデルAPIの認証情報と構成をTealium関数に安全に保存します。

MLプラットフォームの認証トークンを追加する

Tealiumプラットフォームの関数にAPI認証情報を保存するには、認証トークンを追加します。この例では、APIキーまたはトークンエンドポイントURLをmodel_api_tokenとして保存します。詳細については、認証を追加するを参照してください。

関数でトークンを取得するには、次のコードを使用します：

    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer ' + helper.getAuth('model_api_token'),
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(payload)
    }

認証トークンは、HTTPリクエスト内の関数からのみ参照できます。HTTPリクエストの外でトークンを参照しようとすると、トークンはUUIDプレースホルダーに置き換えられます。

MLプラットフォームのグローバル変数を追加する

関数のための構成情報、例えばモデルエンドポイントのURLや名前をグローバル変数として保存します。この例では、モデルエンドポイントのURLをMODEL_ENDPOINT_URLとして保存します。詳細については、グローバル変数を管理するを参照してください。

関数で変数を取得するには、次のコードを使用します：

  const response = await fetch(
    helper.getGlobalVariable('MODEL_ENDPOINT_URL'),
...
    }
  );

ステップ3: ビジタープロファイルにチャーンスコアを追加する

予測を下流システムで活用する前に、モデルの出力をビジタープロファイルに保存して処理するための属性とエンリッチメントを構成する必要があります。

チャーンスコアプロファイル属性を作成する

ビジタープロファイルにモデルの予測を保存するための属性を作成します。この例では、churn_scoreという数値属性を作成します。

詳細については、属性を作成するを参照してください。

作成した属性にモデルの予測をイベントからビジタープロファイルに書き込むためのエンリッチメントを作成します。エンリッチメントがなければ、予測はビジタープロファイルに表示されません。この例では、tealium_eventがmodel_prediction（またはあなたのイベント名）と等しい場合に、track()コールからprediction_scoreイベント属性をchurn_scoreビジター属性に書き込むエンリッチメントを作成します。

詳細については、エンリッチメントを追加するを参照してください。

ステップ4: 高リスクのチャーンオーディエンスを活性化する

予測属性を使用してオーディエンスを構築し、チャーンリスクに基づいてアクションをトリガーして活性化します。

チャーンリスクオーディエンスの作成

予測属性に基づいてオーディエンスを作成します。この例では、churn_scoreが0.7を超える訪問のためにHigh Churn Riskオーディエンスを作成します。

詳細については、オーディエンスの作成を参照してください。

コネクタの構成

予測値に基づいてオーディエンスにコネクタアクションをアタッチしてアクティベートします。この例では、高いチャーンリスクのためのリテンションメールをトリガーしたり、購買意向に基づいてユーザーをリマーケティングオーディエンスに追加することができます。

詳細については、コネクタの追加を参照してください。

デバッグ

ログの表示

デバッグにはconsole.log()を使用します：

console.log('Payload:', JSON.stringify(payload));
console.log('Response status:', response.status);
console.log('Result:', JSON.stringify(result));

ログを表示するには、関数エディターのログタブをクリックします。

一般的な問題

リソース

• 関数