Quick Audience:ユーザー定義関数 UDF 統合管理

1. UDF の説明

UDF（ユーザー定義関数）は、一般的なデータ開発プラットフォームで使用されるユーザー定義関数です。以下の例では、カスタムコンポーネントの代わりに UDF を使用します。

UDF アクセスは、構成と実行で構成されます。構成は API 管理とキャンバス構成コンポーネントに使用され、実行はジャーニー実行中のコールバックに使用されます。実行部分は Webhook に似ています。

2. UDF の構成とアクセスドキュメント

Quick Audience に接続するには、HTTP サーバーを開発する必要があります。Post リクエストであり、リクエストタイムアウト期間は 10 秒であることに注意してください。次の表に、Quick Audience によって開始され、リクエストを受信する HTTP リクエストの共通パラメーターを示します。これらのパラメーターは必須です。

2.1 システム間のフロー API ダイアグラム

① 「オフライン開発」の構成情報を次のように提供します

② iframe ページにジャンプし、外部システムにジャンプします

③ API：トークンを使用してユーザー情報を取得します。同時に、結果は iframe ページに返される必要があります。

④ API：トークンを使用してタグ情報を取得します。同時に、結果は iframe ページに返される必要があります。

⑤ フロントエンドは iframe ページに埋め込まれた API にデータを送信し、外部システムのバックグラウンドは ⑥ を介して QA にデータを送信します

⑥ API：構成情報を QA に送信し、QA は選択されたタグ情報に従ってプロセスを実行します

2.1.1 製品 API 構成 UDF コンポーネント情報

フィールドの制限：

2.1.1.1 元の JSON 情報の構成

{
    "name":"カスタムコンポーネント名",
    "type":"marketing", // カスタムコンポーネントカテゴリ：現在、marketing -> マーケティングコンポーネントのみがサポートされています。
    "version":"バージョン番号", // デフォルト 1.0
    "endpoint":"カスタムコンポーネントのターゲットドメインは http または https で始まります。例：http://demo.com /2 番目のレベルのパス/index.html",
    "iconUrl":"アイコンアドレス",
    "enable": true, // true または false で有効にするかどうか
    "accessKey":"コンポーネント認証用の AccessKey",
    "accessSecret":"AccessKey シークレット",
    "metaData":{ // メタデータ情報。メタデータの形式は、タイプコンポーネントの形式とは異なります。
        "allowIDType":"このコンポーネントは、モバイル、メール、idfa、imei などのユーザー ID タイプをサポートしています",
        "encryptionMethod":"プッシュマーケティングメッセージ暗号化アルゴリズム null | encryptionMethod",
        "sendParam":{
            "batchSendUrl":"マーケティングタスクをプッシュするための URL は、http://demo.com/send など、http または httpss で始まります。",
            "batchLimit":100, // 一度にプッシュされるレコードの最大数。デフォルト値は 1 から 1000.100 です。
            "timeout": 10, // リクエストタイムアウト期間（単位：秒）0 から 60。デフォルト値：10。
            "retryTimes":0, // 許可される再試行回数。デフォルト値：0。デフォルト値：0。
            "retryPeriod":0 // 再試行間隔（秒単位）0 から 3600。デフォルト値：0。
        },
        "callbackParam":{// マーケティングコンポーネント受信パラメーター
            "usableInHours": 3 * 24, //1 から 30 * 24。デフォルト値：3。プッシュ結果受信データが有効な日数。日数を超えると、データは破棄されます。
            "clearInHours": 7 * 24, //1 から 365 * 24。デフォルトでは、結果受信データがリサイクルされるまでの日数。
            "resultEnumList":[ // プッシュ結果受信のリスト。デフォルト値：success と fail。
                {
                    "code":"success",
                    "name":"成功"
                },
                {
                    "code":"fail",
                    "name":"失敗"
                }
            ],
            "extParams": {
              "extParam1": "拡張パラメーター列ヘッダー 001", // 効果分析に表示される列の名前。拡張フィールド 01
              "extParam2": "拡張パラメーター列ヘッダー 002", // 効果分析に表示される列名。拡張フィールド 02
              "extParam3": "拡張パラメーター列ヘッダー 003" // 効果分析に表示される列名。拡張フィールド 03
            }
        }
    }
}

2.1.2 iframe ジャンプ

外部システムは iframe ページを提供する必要があり、ページリンクは前のステップで構成されたエンドポイントに入力されます。

注：クロスドメインの問題が発生し、クロスドメインサポートを追加する必要があります。X-Frame-Options: allow-from https://example.com/

ジャンプ URL

/endPoint?comeFrom=xxx&qaEndpoint=xxx&token=xxx

成功応答のサンプル

{
  "success":true,
  "errorDesc":"エラーメッセージ（空にすることも可能）"
}

2.1.3 API 操作：トークンを使用してユーザー情報を取得する

API：/openapi/v3/account/query?token=xxx

戻り値：

{
  "success": false,
  "errorDesc": "",
  "data": {
    "organizationId":"組織 ID",
    "organizationName":"組織名",
    "userId":"ユーザー ID",
    "nickName":"ユーザーニックネーム"
  },
  "@comment": {
    "success": "/**\n * 列挙値：true | false\n */",
    "errorDesc": "/**\n * エラーメッセージの説明 \n */",
    "data": "/**\n * ユーザー情報 \n */"
  }
}

ユーザー情報が取得された場合、システムは正常に利用可能です。ユーザー情報が取得されない場合、ページのレンダリング時にトークン無効エラーメッセージが返されます。

2.1.4 API：UDF によって選択されたクラウドとイベント ID を保存します。

API：/restapi/marketing/udf_component/genUdfComponentNode

入力パラメーター：

{
    "componentId": "1001",
    "sourceId": "c1f5691dd5864479820c10c0089bece9 (イベントまたはクラウドの ID)",
    "sourceNodeId": "",
    "nodeId": "83a2d328-030d-436a-b607-21da8ee2e34b",
    "sourceType": 1 // イベントのタイプ。1 はクラウド、2 はイベントを示します。
}

戻り値：

{
    "data": {
        "nodeId": "83a2d328-030d-436a-b607-21da8ee2e34b",
        "token": "zKBfv7flRQmhd+XP1l1uuKCjE6seEOq8l02cBFWWRr5xQoOUPxb3+tj+ZPctWDG4rM5vC2PMQLxG0Xw7Qw6TpsDfXSYFwD8kmTjpUOV4AjxQfZPfC5q0wPrEFhvgfjz9X1OKDu4V4p1oJnJcbt5nELidsVk6jxkbVwHEL8ezXcyXFRKbC+jVYxOwG5ElUhS0+hraAK5IiwR1XgZCarFgOGf5ZZo/Nacjrp5AP8HbF3tl4+thAjp8ZuMWTYXsBJbe"
    },
    "errorCode": null,
    "errorDesc": null,
    "exStack": null,
    "opers": [],
    "solution": null,
    "success": true,
    "traceId": "48d6e570-1918-47a4-83ee-27c3f32d3a99"
}

2.1.5 API：トークンでクラウドラベルリスト/イベント属性リストを取得する（1.4 に依存）

API：/openapi/v3/udf_component/marketing/getNodeUsableLabels?token=xxx&nodeId=xxx&version=VERSION_2

戻り値：

[
    {
        "id": "タグ ID /プロパティ ID",
        "name": "ラベル名 /属性名"
    }
]

選択されたタグと属性は、サードパーティシステムが最終的に転送されるときにパラメーターとして渡されます。

2.1.6 フロントエンドが iframe 埋め込みページにデータを送信するための API

このページパラメーターはサードパーティによって定義されます。ページが最終的に実行されると、QA によってサードパーティに呼び出され、サードパーティが実行します。ただし、選択された QA タグは ⑥ の API を介して QA に返される必要があります。

2.1.7 UDF 構成情報を送信する

API： /openapi/v3/udf_component/marketing/saveOrUpdateNodeConfig?token=xxx

リクエスト本文：

{
  "nodeId": "ノード ID",
  "nodeName": "ノード名",
  "labelIdList": [
    "タグ ID1",
    "ラベル ID2"
  ]
}

戻り値：戻り値なし。HTTP ステータスは 200 です。

3. UDF 実行アクセスドキュメント

システムフローダイアグラムは次のように表示されます

3.1 ノード実行リクエスト

Quick Audience に接続するには、HTTP サーバーを開発する必要があります。Post リクエストであり、リクエストタイムアウト期間は 10 秒であることに注意してください。次の表に、Quick Audience リクエストとアクセス受信リクエストの共通パラメーターを示します。

リクエスト URL：{sendParam.batchSendUrl }

リクエストヘッダー情報

ヘッダー情報を読み取った後、java.net.URLDecoder#decode(java.lang.String, java.lang.String) で UTF-8 にエンコードする必要があります。

v=4 // 固定パラメーター。新しいバージョンと古いバージョンを区別するために使用されます。新しいバージョンは 4 で、古いバージョンにはこのフィールドがありません。

リクエスト本文：

リクエスト本文のサンプル

{
  "time": 0,
  "requestId": "111",
  "componentId": "111",
  "accessKey": "111",
  "signature": "111",
  "encryptionMethod": [
    "AES"
  ],
  "data": "文字列形式。詳細な形式は次のとおりです"
}

// データ形式。
{
    "jobId": "",
    "jobName": "",
    "nodeId": "",
    "nodeName": "",
    "componentName": "",
    "taskId": "",
    "taskStartTimestamp": 0,
    "nodeStartTimestamp": 0,
    "data": {
      "messageId": "",
      "customerList": [
        {
          "customerId": "",
          "labels": {},
          "featureMap": {
            "受信フィールド":"そのまま戻す"
          },
          "processInfo": {
            "processInstanceId": "新バージョン：ジャーニーサイクルにおける各ユーザーのジャーニーインスタンス ID",
            "processInstanceStartTime": "新バージョン：ジャーニー期間における各ユーザーのジャーニーインスタンスの開始時刻（タイムスタンプ形式）",
            "processNodeInstanceId": "新バージョン：ジャーニーノードインスタンス ID（毎回異なる）",
            "processNodeInstanceStartTime": "新バージョン：ジャーニー期間における各ユーザーのジャーニーのノードインスタンス開始時刻（タイムスタンプ形式）",
            "groupName":"nodeId:nodeName:groupResult(node.result),groupName(node.resultExt);nodeId:nodeName:groupResult(node.result),groupName(node.resultExt)",
            "@comment":{
              "groupName" : "ノード ID：ノード名（API で構成）：グループ化結果（ランダムグループ化のパーセンテージ数、小数点以下 2 桁）：グループ名（API で構成）。複数ある場合はセミコロンで区切る"
            }
        	}
          "@comment": {
            "featureMap": "/**\n * 拡張フィールド。非同期受信中にダウンストリームで返される必要があります \n */"
          }
        }
      ]
    },
    "activityId": "",
    "activityName": "",
    "subActivityId": "",
    "subActivityName": "",
    "processId": "",
    "processName": "",
    "processInstanceId": "",
    "processInstanceName": "",
    "processInstanceStartTime": "",
    "processNodeId": "",
    "processNodeName": "",
    "processNodeInstanceId": "",
    "processNodeInstanceStartTime": "",
    "groupId": "",
    "groupName": "",
    "@comment": {
      "activityId": "/**\n * アクティビティ ID\n */",
      "activityName": "/**\n * アクティビティ名 \n */",
      "subActivityId": "/**\n * 子アクティビティの ID \n */",
      "subActivityName": "/**\n * 子アクティビティ名 \n */",
      "processId": "/**\n * ジャーニー ID（自動化 ID）。アクティビティ ID\n */",
      "processName": "/**\n * ジャーニー名（自動化名）。アクティビティ名 \n */",
      "processInstanceId": "/**\n * ジャーニーインスタンス ID。アクティビティインスタンス ID\n */",
      "processInstanceName": "/**\n * アクティビティインスタンスの名前（アクティビティの時刻）\n */",
      "processInstanceStartTime": "/**\n * アクティビティインスタンス開始時刻 \n */",
      "processNodeId": "/**\n * アクティブノードの ID \n */",
      "processNodeName": "/**\n * アクティビティノード名 \n */",
      "processNodeInstanceId": "/**\n * アクティブノードインスタンスの ID \n */",
      "processNodeInstanceStartTime": "/**\n * アクティブノードインスタンス開始時刻 \n */",
      "groupId": "/**\n * ABTest グループの ID。このパラメーターは空です。 \n */",
      "groupName": "/**\n * ABTest グループ名（null）\n */"
    }
  }

戻り値：

{
  "success": true,
  "errorDesc": "エラーメッセージ",
  "customerList": [
    {
      "messageId": "メッセージ ID",
      "customerId": "顧客 ID",
      "returnType": "受信結果。この結果は受信結果と同じです。1 つある場合は、直接受信結果と見なされます。受信結果を直接入力したくない場合は、渡さないでください",
      "featureMap": {
        "受信フィールド":"そのまま戻す"
      },
          "processInfo": {
            "processInstanceId": "新バージョン：ジャーニーサイクルにおける各ユーザーのジャーニーインスタンス ID",
            "processInstanceStartTime": "新バージョン：ジャーニー期間における各ユーザーのジャーニーインスタンスの開始時刻（タイムスタンプ形式）",
            "processNodeInstanceId": "新バージョン：ジャーニーノードインスタンス ID（毎回異なる）",
            "processNodeInstanceStartTime": "新バージョン：ジャーニー期間における各ユーザーのジャーニーのノードインスタンス開始時刻（タイムスタンプ形式）"
        	}
    }
  ]
}

3.1.1 認証モード

署名アルゴリズム

long sendTime = System.currentTimeMillis();
// コンポーネントの ID です。
// Component AK
// Component sk

String sign = getSignatureByHmacSHA1(sendTime, componentModel.getComponentId(), componentModel.getAccessKey(), componentModel.getAccessSecret());

public static String getSignatureByHmacSHA1(long time, String prametersString, String accessKey, String accessSecret) {
    String str = time + prametersString + accessKey;
    return HmacUtils.hmacSha256Hex(accessSecret, str.replaceAll("\\s+", ""));
}

3.2 領収書レポート

UDF の例を次に示します。

例 1：

API : /restapi/marketing2/udfComponent/receiveCallback?

例 2：

{
  "time": 0,
  "componentId": "UDF コンポーネント ID",
  "signature": "署名",
  "data": "暗号化された領収書情報。文字列です。",
  "@comment":{
    "time":"領収書のタイムスタンプ（ミリ秒単位）"
  }
}

// データの元のフォーマット
{
  "nodeId": "ノード ID",
  "taskId": "タスク ID",
  "customerList": [
    {
      "messageId": "メッセージ ID",
      "customerId": "顧客 ID",
      "returnType": "領収書の結果",
      "sendTimestamp": 0,
      "featureMap": {
        "request parameters": "戻り値"
      },
      "@comment": {
        "messageId": "/**\n * メッセージの ID。この ID は、QA がメッセージをプッシュするときに含まれます。\n */",
        "customerId": "/**\n * ユーザー ID\n */",
        "returnType": "/**\n * 領収書の結果\n */",
        "sendTimestamp": "/**\n * メッセージのプッシュ時間\n */",
        "featureMap": "リクエストの送信に使用されたパラメーター。領収書に戻す必要があります。"
      },
      "extParam1": "拡張パラメーター 001-カスタム戻り値",
      "extParam2": "拡張パラメーター 002-カスタム戻り値",
      "extParam3": "拡張パラメーター 003-カスタム戻り値"
    }
  ],
  "@comment": {
    "nodeId": "/**\n * ノード ID\n */",
    "taskId": "/**\n * タスク ID\n */",
    "customerList": "/**\n * 領収書のユーザー/フォロワーのリスト\n */"
  }
}

注: この例では、fetch API を使用しています。他の JavaScript ライブラリも使用できます。

{
  "success": true,
  "errorDesc": "",
  "@comment": {
    "success": "/**\n * 列挙値：true | false\n */",
    "errorDesc": "/**\n * エラーメッセージの説明\n */",
    "data": "/**\n * ユーザー情報\n */"
  }
}