사용자 정의: 필드 및 모듈
Flash는 하나의 공유 코드베이스를 기반으로 각 브랜드에 맞게 두 가지 방식으로 설계되었으며, 포크는 절대 발생하지 않습니다. 사용자 정의 필드는 회원 기록에 사용자 지정 데이터를 추가할 수 있으며, v2 REST API를 통해 설정할 수 있습니다. 모듈은 워크스페이스별로 활성화/비활성화할 수 있는 선택적 기능이며, 서버에서 활성화 여부를 강제합니다. 이 가이드에서는 두 가지 모두를 다룹니다.
필드는 설정되기 전에 선언됩니다.
소유자 또는 관리자는 설정 → 사용자 지정 필드에서 필드를 생성합니다. 각 필드에는 키(예: cf_membership_no와 같은 머신 이름), 유형, 그리고 선택된 유형의 경우 옵션 목록이 있습니다. 키와 유형은 생성 후 고정됩니다. API는 필드를 생성하지 않고, 이미 존재하는 필드에 값만 설정하며, 알 수 없는 키는 거부합니다. 정의 테이블이 허용 목록 역할을 합니다.
생성 또는 업데이트 시 customAttributes 전달
POST /api/v2/members(생성) 및 PATCH /api/v2/members/{id}(업데이트) 모두 필드 키를 키로 사용하는 customAttributes object을 허용합니다. 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" | 끈 |
number | 42 | number (또는 숫자 string) |
date | "2018-05-01" | ISO 날짜(YYYY-MM-DD) |
boolean | true | 참/거짓 |
enum | "flagship" | 필드의 옵션 중 하나 |
list | ["running","tennis"] | 해당 필드 옵션의 하위 집합 |
유효성 검사는 엄격합니다. 값은 해당 필드의 유형과 일치해야 하며, enum/list 값은 정의된 옵션 중 하나여야 하며, 알 수 없는 키는 400로 거부됩니다. 민감한 개인 데이터(PII) 필드는 아직 허용되지 않습니다. 민감하지 않은 비즈니스 가치에 대한 맞춤 속성을 유지하세요.
플랫폼 전체에서 사용되는 단일 값
세그먼트
유형에 맞는 연산자를 사용하여 모든 사용자 지정 필드(API에서 설정한 것과 동일한 필드)로 멤버를 필터링할 수 있습니다.
이메일 개인화
복사본에서 값을 {{cf_membership_no}} 또는 {{member.cf_membership_no}}로 참조하십시오.
회원이 읽음
회원 object의 customAttributes 항목에 사용자 지정 값이 반환됩니다.
워크스페이스별로 활성화/비활성화할 수 있는 선택적 기능입니다.
사용자 정의 필드가 값을 추가하는 것처럼, 모듈은 전체 기능을 추가합니다. 예를 들어 서비스 티켓 모듈, 예약 또는 수리 로그 등이 있습니다. 모듈은 기본적으로 비활성화되어 있으며 워크스페이스별로 활성화됩니다. 모든 워크스페이스는 동일한 코드베이스를 실행합니다. 모듈의 활성화 또는 비활성화는 데이터(권한)이며, 개인 빌드와는 무관합니다.
서버에 의해 한 곳에서 시행
각 모듈에는 고정 키(예: tickets)가 있습니다. 워크스페이스에서 해당 모듈을 사용할 수 있는지 여부는 워크스페이스별로 하나의 스위치로 설정할 수 있으며, 한 번의 판단 시점에서 확인 후 모듈이 나타나는 모든 곳에 적용됩니다. fail-closed: 스위치가 켜져 있지 않으면 해당 기능은 사용할 수 없습니다.
API
비활성화된 모듈의 끝점은 403을 사용한 호출을 거부합니다. UI만으로는 액세스가 우연히 이루어지지 않습니다.
탐색 및 페이지
모듈의 메뉴 항목과 페이지는 워크스페이스에서 해당 모듈이 활성화된 경우에만 표시되며, 비활성화되면 깔끔하게 사라집니다.
테넌트 격리
권한은 워크스페이스별로 부여됩니다. 한 브랜드의 모듈과 데이터는 다른 브랜드에서 절대 볼 수 없습니다.
새 모듈 도입 방법
기능이 실제로 재사용 가능하면 모듈로 한 번 구축됩니다. 즉, 자체 데이터, 자체 자격 부여 API 및 자체 페이지와 함께 해당 키 아래의 모듈 카탈로그에 등록됩니다. 이를 필요로 하는 첫 번째 작업 공간이 구축됩니다. 다음은 스위치를 뒤집는 것뿐입니다. 이것이 모델의 핵심입니다. 고객 차이가 설정으로 표현되므로 하나의 업그레이드 또는 수정이 모든 작업 공간에 동시에 적용됩니다.
- 모듈은 안정적인 키와 설명으로 카탈로그에 등록됩니다.
- 데이터와 API 경로는 해당 키(fail-closed)로 보호됩니다.
- 키가 활성화된 경우에만 탐색 메뉴와 페이지가 표시됩니다.
- 소유자가 작업 공간으로 사용하기 위해 전원을 켜는 방식입니다. 두 번째 작업 공간은 스위치를 켜는 것이지, 재구축하는 것이 아닙니다.
모듈 켜기 또는 끄기
작업공간 소유자는 설정 → 모듈에서 모듈을 관리합니다. 각 토글은 API 및 UI 전체에 즉시 적용됩니다.
결정 규칙: 먼저 구성을 사용하고, 값을 저장해야 할 때 사용자 지정 필드를 추가하고, 기능이 진정으로 재사용 가능한 경우 모듈을 구축하고, 단일 고객을 위해 제품을 포크하지 마십시오.
추가 필드가 아닌 완전히 새로운 종류의 레코드가 필요합니까? 사용자 정의 개체를 참조하세요. 자신만의 코드 없는 비즈니스 개체를 만든 다음 레코드를 찾아보고 그에 대한 세그먼트를 분류하세요. 스택의 나머지 부분을 동기화 상태로 유지하려면 커넥터 및 알림을 참조하세요.