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

このガイドでは、外部AIモデルをTealiumの関数と統合してリアルタイムでアクティベーションするための概念とコンポーネントについて説明します。モデルエンドポイントに安全に接続し、イベントデータと訪問データを使用してAI予測を呼び出し、モデルの出力で訪問プロファイルを豊かにし、これらの洞察を利用して下流のアクションを推進する方法を学びます。また、タイムアウトの管理、非同期応答の処理、一般的な統合問題の解決方法についても説明します。

動作原理

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

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

1. 顧客のアクション：ユーザーがアクションを実行します（例：商品を見る、カートに追加する、フォームを送信する）。
2. 関数トリガー：構成されたトリガーに基づいてイベントまたは訪問関数が発火し、予測（スコア、分類、推奨）を返します。
3. イベントを収集：関数は予測データをTealium Collectにtrack()メソッドを通じて送信します。
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 Functionsが有効になっていること
  • 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('モデルAPIエラー:', 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('モデルAPIエラー:', 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')
  };
  // 応答を待たずに発火 - don't await the response
  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('リクエスト失敗:', 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で説明されているように、これらの属性をプロファイルに書き込むためにエンリッチメントを構成します。

タイムアウト処理

fetch() APIはネットワーク障害時にのみエラーを返し、4xx/5xxのレスポンスではエラーを返しません。モデルエンドポイントが遅い場合に関数がハングアップするのを防ぐために、タイムアウトを強制するために AbortController を使用します：

const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 8000);
try {
  const response = await fetch(url, {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer ' + helper.getAuth('model_api_token'),
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(payload),
    signal: controller.signal
  });
  clearTimeout(timeoutId);
  if (!response.ok) {
    console.error('モデルAPIエラー:', response.status);
    return;
  }
  const result = await response.json();
} catch (error) {
  if (error.name === 'AbortError') {
    console.error('リクエストがタイムアウトしました');
  } else {
    console.error('Fetchエラー:', error.message);
  }
}

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

Tealium関数でモデルAPIの認証情報と構成を安全にアクセスするために保存します。

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)
    }

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));

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

一般的な問題

リソース

• 関数