Quick Audience:ユーザー定義 UDF のアクセス管理

1. UDF の説明

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

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

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

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

2.1 システム間のフローインターフェイス図

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

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

③ API インターフェイス：トークンを介してユーザー情報を取得します。同時に、結果を iframe ページに返す必要があります。

④ API インターフェイス：トークンによってタグ情報を取得します。同時に、結果を iframe ページに返す必要があります。

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

⑥ API インターフェイス：設定情報を QA に送信し、QA は選択されたタグ情報に従ってプロセスを実行します。

2.1.1 プロダクトインターフェイスでの UDF コンポーネント情報の設定

フィールドの制限：

2.1.1.1 元の JSON 情報の構成

{
    "name":"カスタムコンポーネント名",
    "type":"marketing", // カスタムコンポーネントのカテゴリ：現在、marketing -> マーケティングコンポーネントのみがサポートされています。
    "version":"バージョン番号", // デフォルトは 1.0
    "endpoint":"カスタムコンポーネントのターゲットドメイン名。http または https で始まります。例：http://demo.com /second-level path to point/index.html",
    "iconUrl":"アイコンアドレス",
    "enable": true // true または false、有効にするかどうか
    "accessKey":"コンポーネント認証用の AccessKey",
    "accessSecret":"AccessKey Secret",
    "metaData":{ // メタデータ情報。メタデータのフォーマットは、タイプコンポーネントのフォーマットとは異なります。
        "allowIDType":"このコンポーネントがサポートするユーザー ID タイプ。例：mobile、email、idfa、imei",
        "encryptionMethod":"プッシュマーケティングメッセージの暗号化アルゴリズム null | encryptionMethod",
        "sendParam":{
            "batchSendUrl":"マーケティングタスクをプッシュするための URL。http または https で始まります。例：http://demo.com/send",
            "batchLimit":100, // 一度にプッシュするレコード数。値は 1 から 1000 です。デフォルト値は 100 です。
            "timeout": 10, // リクエストのタイムアウト期間 (単位：秒) 0 から 60。デフォルト値：10。
            "retryTimes":0, // 失敗した場合のリトライ回数。0 から 3。デフォルト値：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 操作：トークンを使用したクラウドタグリストとイベント属性リストの取得 (2.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 タグは ⑥ のインターフェイスを介して QA に返す必要があります。

2.1.7 UDF 設定情報の送信 (2.1.5 に依存)

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

リクエスト本文：

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

戻り値：戻り値なし。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": "",
          "featureMap": {
            "受信フィールド":"そのまま返します"
          },
          "idMappings": {
                    "mobile": "携帯電話番号",// インスタンスの ID タイプ。
                    "qaid": "QA によって生成された QAID"
                },
                "labels": {},
          "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：ノード名 (インターフェイスで設定)：グループ化結果 (ランダムグループ化のパーセンテージ、小数点以下 2 桁)：グループ名 (インターフェイスで設定)；複数ある場合はセミコロンで区切ります"
            }
        	}
          "@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": "受信結果。この値が存在する場合、直接受信結果とみなされます。受信結果を直接入力したくない場合は、このパラメーターを渡さないでください。",
      "returnMessage": "受信メッセージの長さは 255 文字です。長さが制限を超えた場合、メッセージは自動的に切り捨てられます。"
    }
  ]
}

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 領収書レポート

アクセスポイントがマーケティングタスクを実行すると、マーケティングメッセージの送信結果をフィードバックとして Quick Audience に報告します。

HTTPリクエストURL:

API : /restapi/marketing2/udfComponent/receiveCallback?

リクエストボディ：

{
  "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 */"
  }
}

戻り値：

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