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

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

仕組み

機能を使用して、顧客離脱リスク、詐欺検出、傾向スコアリング、次善のアクション推奨などのタスクのために外部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 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)
    }

認証トークンは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));

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

一般的な問題

リソース

• 関数