SocialHub.AI
開発者センター · REST API

カスタマイズ: フィールドとモジュール

Flash は各ブランドに合わせて 2 つの方法で形成されており、どちらも 1 つの共有コード ベース上にあり、決してフォークではありません。 カスタム フィールド は、メンバー レコードに独自のデータを追加し、v2 REST API を通じて設定されます。 モジュール は、ワークスペースごとに切り替えられ、サーバーによって強制されるオプションの機能です。このガイドでは両方について説明します。

ステップ 1 — フィールドを定義します (アプリ内)

フィールドは設定される前に宣言されます

所有者または管理者は、[設定] → [カスタム フィールド] でフィールドを作成します。各フィールドには、キー (マシン名、例: cf_membership_no)、タイプ、および (選択タイプの場合) オプションのリストがあります。キーとタイプは作成後に固定されます。 API はフィールドを作成しません。すでに存在するフィールドの値のみを設定し、不明なキーは拒否します。定義テーブルは許可リストです。

ステップ 2 — API を介して値を設定します

作成または更新時に customAttributes を渡します

POST /api/v2/members (作成) と PATCH /api/v2/members/{id} (更新) はどちらも、フィールド キーをキーとする customAttributes オブジェクトを受け入れます。 members:write スコープを持つ Bearer fl_live_ キーを使用して認証します。

curl -X POST https://flash.socialhub.ai/api/v2/members \
  -H "Authorization: Bearer fl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ada@example.com",
    "fullName": "Ada Lovelace",
    "customAttributes": {
      "cf_membership_no": "A-10023",
      "cf_preferred_store": "flagship",
      "cf_child_birthday": "2018-05-01"
    }
  }'

更新時には、変更したいキーのみを送信します。キーを null に設定すると、キーがクリアされます。

curl -X PATCH https://flash.socialhub.ai/api/v2/members/{id} \
  -H "Authorization: Bearer fl_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "customAttributes": { "cf_preferred_store": "airport" } }'
タイプ別の値の形状

各フィールドタイプが受け入れるもの

タイプJSON値の例受け入れる
text"A-10023"弦
number42数値 (または数値文字列)
date"2018-05-01"ISO 日付 (YYYY-MM-DD)
booleantrue真 / 偽
enum"flagship"フィールドのオプションの 1 つ
list["running","tennis"]フィールドのオプションのサブセット

検証は厳密です。値はフィールドのタイプと一致する必要があり、enum/list 値は定義されたオプションの 1 つである必要があり、不明なキーは 400 で拒否されます。機密個人データ (PII) のフィールドはまだ受け入れられていません。カスタム属性は機密性の低いビジネス値に保ってください。

下流で得られるもの

プラットフォーム全体で使用される 1 つの値

セグメント

タイプに適した演算子を使用したカスタム フィールド (API で設定したものと同じフィールド) でメンバーをフィルターします。

電子メールのパーソナライゼーション

コピー内の値を {{cf_membership_no}} または {{member.cf_membership_no}} として参照します。

メンバーが読んだ

カスタム値は、customAttributes のメンバー オブジェクトで返されます。

②モジュール

オプション機能(ワークスペースごとにオン)

カスタム フィールドが 値 を追加する場合、モジュールは全体の 機能 を追加します。サービス チケット モジュール、予定、修理ログなどを考えてください。モジュールはデフォルトではオフになっており、ワークスペースごとに有効になります。すべてのワークスペースは同じコードベースを実行します。オンまたはオフになっているモジュールは データ (権利) であり、プライベート ビルドではありません。

ゲートの仕組み

サーバーによって 1 か所で強制されます

各モジュールには安定したキー (例: tickets) があります。ワークスペースがそれを使用できるかどうかは、ワークスペースごとに 1 つのスイッチであり、1 つの判断ポイントでチェックされ、モジュールが表示されるすべての場所に適用されます。フェイルクローズ: スイッチがオンになっていない場合、その機能は単に存在しません。

API

無効化されたモジュールのエンドポイントは、403 による呼び出しを拒否します。 UI だけでアクセスが偶然に任せられることはありません。

ナビゲーションとページ

モジュールのメニュー エントリとページは、ワークスペースで有効になっている場合にのみ表示され、オフにするときれいに消えます。

テナントから分離

権限はワークスペースごとに付与されます。あるブランドのモジュールとデータが別のブランドに表示されることはありません。

分岐せずに拡張する

新しいモジュールの導入方法

機能が真に再利用可能な場合、その機能はモジュールとして一度構築され、独自のデータ、独自の資格ゲート型 API および独自のページとともに、そのキーの下でモジュール カタログに登録されます。それを必要とする最初のワークスペースでそれが構築されます。次はスイッチを入れるだけです。これがモデルの中核です。顧客の違いは設定として表現されるため、1 つのアップグレードまたは修正がすべてのワークスペースに一度に適用されます。

  1. モジュールは、安定したキーと説明を使用してカタログに登録されます。
  2. そのデータと API ルートはそのキーでゲートされます (フェールクローズ)。
  3. そのナビゲーションとページは、キーが有効になっている場合にのみ表示されます。
  4. 所有者がワークスペースに対してこれをオンにします。 2 番目のワークスペースは切り替えであり、再構築ではありません。
モジュールの管理

モジュールをオンまたはオフにする

ワークスペース所有者は、[設定] → [モジュール] からモジュールを管理します。各切り替えは、API と UI 間ですぐに有効になります。

決定ルール: 最初に設定を使用します。値を保存する必要がある場合は、カスタム フィールドを追加します。機能が本当に再利用可能な場合にモジュールを構築し、単一の顧客のために製品をフォークしないでください。

単なる追加フィールドではなく、まったく新しい種類のレコードが必要ですか? カスタム オブジェクト を参照してください。コードを必要としない独自のビジネス オブジェクトを構築し、レコードを参照してセグメント化します。スタックの残りの部分の同期を保つには、「コネクタと通知」を参照してください。