Control Groups API

Control group คือส่วนแบ่งผู้ใช้ของแอปพลิเคชันที่ไม่เคยได้รับข้อความทางการตลาด เพื่อให้สามารถวัดผลของข้อความเปรียบเทียบกับกลุ่มนี้ได้ API นี้จัดการ control groups และตอบคำถามเกี่ยวกับสถานะสมาชิกของผู้ใช้แต่ละราย ใช้ API นี้เพื่อจำลองการทำงานของ Settings > Control groups ใน Control Panel จากระบบของคุณเอง หรือเพื่อตรวจสอบว่า User ID ที่ระบุถูกกันออกไปก่อนที่จะส่งข้อความหรือนำเข้าข้อมูลหรือไม่

Base URL

https://rpc-api.svc-nue.pushwoosh.com

Endpoints ทั้งหมดให้บริการผ่าน HTTPS คำขอและการตอบกลับใช้ application/json เว้นแต่จะระบุไว้เป็นอย่างอื่น

การรับรองความถูกต้อง

ทุกคำขอต้องมี Authorization header พร้อมกับ Server API token ของคุณ:

Authorization: Api YOUR_API_TOKEN

ข้อตกลงทั่วไป

การตั้งชื่อฟิลด์: request bodies และพารามิเตอร์ query/path ยอมรับ lowerCamelCase (ตัวอย่างเช่น controlGroupCode, userIds) และเซิร์ฟเวอร์จะ unmarshal ทั้งสองรูปแบบ การตอบกลับจะถูก marshal โดยใช้ชื่อฟิลด์ของ proto เสมอ ในรูปแบบ snake_case (application_id, in_control_group และอื่นๆ) ตัวอย่างการตอบกลับและข้อมูลอ้างอิง ออบเจ็กต์ Control group ด้านล่างใช้รูปแบบนั้น
code: การตอบกลับของ control group ทุกครั้งจะมีโค้ดของตัวเอง ซึ่งสร้างขึ้นเมื่อ Create ส่งโค้ดนี้เป็น controlGroupCode ไปยัง Get, UpdatePercentage, UpdateCountries, Rename, Disable, Reshuffle, ForceUpdateCalculation, GetCalculationStatus, GetAnalytics และ CheckControlGroupMembership
หลายกลุ่ม: แอปพลิเคชันสามารถมี control group ได้หลายกลุ่ม ทุกกลุ่มที่เปิดใช้งานจะกันผู้ใช้ออกจากการส่งทางการตลาดทุกครั้งภายในประเทศและแท็กของกลุ่มนั้นเอง โดยไม่ขึ้นกับกลุ่มอื่น และกลุ่มต่างๆ อาจทับซ้อนกันได้ การส่งไม่ได้เลือกกลุ่ม กลุ่มที่มี name ว่างเปล่าคือกลุ่มดั้งเดิมของแอปพลิเคชันและทำงานในลักษณะเดียวกัน

การตอบกลับข้อผิดพลาด

สถานะ HTTP	ความหมาย
`400 Bad Request`	อาร์กิวเมนต์ไม่ถูกต้อง เช่น `percentage` อยู่นอกช่วง 1–20, `userIds` ว่างเปล่าหรือมีมากกว่า 1,000 รายการ รหัสประเทศที่ไม่รู้จัก `scopeValues` ที่ตั้งค่าโดยไม่มี `scopeTag` `scopeTag` ที่ระบุแท็กซึ่งบัญชีไม่มี หรือรายการ `scopeValues` ที่ `UpdateSettings` ปฏิเสธ (ดูด้านล่าง) นอกจากนี้ยังส่งคืน (เป็น `FailedPrecondition` บน wire) โดย `UpdatePercentage`, `UpdateCountries`, `UpdateSettings`, `Disable`, `Reshuffle` และ `Delete` บน control group ที่เป็นของ hold-out ของแคมเปญเอง ตาม ข้อควรระวัง ด้านล่าง `Reshuffle` เพียงอย่างเดียวก็จะปฏิเสธด้วยวิธีนี้ในกลุ่มที่ถูกปิดใช้งาน (`percentage` 0)
`401 Unauthorized`	`Authorization` header หายไปหรือไม่ถูกต้อง
`403 Forbidden`	แอปพลิเคชันหรือ control group ไม่ได้เป็นของบัญชีผู้เรียก
`404 Not Found`	ไม่พบ control group หรือแอปพลิเคชัน
`409 Conflict`	`Create` ใช้ `name` ที่มีอยู่แล้วในแอปพลิเคชัน
`500 Internal Server Error`	เกิดข้อผิดพลาดที่ไม่คาดคิดฝั่งเซิร์ฟเวอร์

Endpoints

เมธอด	เส้นทาง	คำอธิบาย
`GET`	`/api/applications/{code}/control_groups`	แสดงรายการ control groups ของแอปพลิเคชัน
`POST`	`/api/applications/{code}/control_groups`	สร้าง control group
`GET`	`/api/applications/{code}/control_groups/{control_group_code}`	ดึงข้อมูล control group เดียว
`POST`	`/api/applications/{code}/control_groups/{control_group_code}`	ปรับขนาด control group
`POST`	`/api/applications/{code}/control_groups/{control_group_code}/countries`	กำหนดขอบเขต control group ใหม่ตามชุดของประเทศ
`POST`	`/api/applications/{code}/control_groups/{control_group_code}/settings`	ใช้ขนาด ขอบเขตประเทศและแท็ก และโหมดอายุการใช้งานในการเรียกครั้งเดียว
`POST`	`/api/applications/{code}/control_groups/{control_group_code}/display_name`	เปลี่ยนชื่อ control group
`POST`	`/api/applications/{code}/control_groups/{control_group_code}/disable`	ปิดใช้งาน control group
`POST`	`/api/applications/{code}/control_groups/{control_group_code}/reshuffle`	สับเปลี่ยน control group
`POST`	`/api/applications/{code}/control_groups/{control_group_code}/recalculate`	บังคับคำนวณขนาดของ control group ใหม่
`GET`	`/api/applications/{code}/control_groups/{control_group_code}/calculation_status`	ตรวจสอบสถานะการคำนวณขนาดที่กำลังทำงานอยู่
`GET`	`/api/applications/{code}/control_groups/{control_group_code}/analytics`	ดึงข้อมูลการวิเคราะห์ Control-vs-Treatment
`GET`	`/api/applications/{code}/control_groups/{control_group_code}/cycles`	แสดงรายการรอบที่ปิดแล้วของกลุ่ม
`POST`	`/api/applications/{code}/control_groups/{control_group_code}/membership`	ตรวจสอบสถานะสมาชิกสำหรับชุดของ User ID
`DELETE`	`/api/applications/{code}/control_groups/{control_group_code}`	ลบ control group

List

แสดงรายการ control group ทั้งหมดที่กำหนดค่าไว้สำหรับแอปพลิเคชัน โดยกลุ่มดั้งเดิมที่ไม่มีชื่อจะอยู่ก่อน

GET /api/applications/{code}/control_groups

พารามิเตอร์ของเส้นทาง

พารามิเตอร์	ประเภท	คำอธิบาย
`code`	string	โค้ดแอปพลิเคชัน ที่ต้องการแสดงรายการ control groups

การตอบกลับ

ฟิลด์	ประเภท	คำอธิบาย
`control_groups`	array of Control group objects	control group ทั้งหมดที่กำหนดค่าไว้สำหรับแอปพลิเคชัน

Create

สร้าง control group ที่มีชื่อสำหรับแอปพลิเคชันและส่งคืนพร้อมกับโค้ดที่สร้างขึ้น กลุ่มใหม่จะกันผู้ใช้ออกจากการส่งทางการตลาดทุกครั้งภายในประเทศและแท็กของกลุ่มนั้นเอง ควบคู่ไปกับกลุ่มอื่นที่เปิดใช้งานของแอปพลิเคชัน

POST /api/applications/{code}/control_groups

Request body

พารามิเตอร์	ประเภท	จำเป็น	คำอธิบาย
`code`	string	ใช่	โค้ดแอปพลิเคชันที่จะสร้างกลุ่มในนั้น
`name`	string	ใช่	ชื่อกลุ่ม, ไม่เกิน 64 ตัวอักษรและไม่มีเครื่องหมายโคลอน ต้องไม่ซ้ำกันภายในแอปพลิเคชัน เป็นส่วนหนึ่งของคีย์สมาชิก จึงไม่เปลี่ยนแปลง
`percentage`	integer	ใช่	ขนาด hold-out เป็นเปอร์เซ็นต์, 1–20
`segment`	string	ไม่	นิพจน์ Seglang เพื่อวัดผลกลุ่ม หากไม่ระบุจะวัดผลจากฐานผู้ใช้ทั้งหมด
`countries`	array of strings	ไม่	รหัสประเทศ ISO-3166-1 alpha-2 ตัวพิมพ์เล็กเพื่อกำหนดขอบเขตของ hold-out หากไม่ระบุจะใช้ทุกประเทศ รหัสจะไม่คำนึงถึงตัวพิมพ์เล็ก-ใหญ่เมื่อป้อนข้อมูล
`scopeTag`	string	ไม่	แท็กชนิด string หรือ boolean ที่ใช้กำหนดขอบเขตของ hold-out โดยใช้เงื่อนไข AND ร่วมกับ `countries` หากไม่ระบุจะไม่มีขอบเขตแท็ก ดู ขอบเขตแท็ก ด้านล่าง
`scopeValues`	array of strings	ดูหมายเหตุ	ค่าของ `scopeTag` ที่ทำให้ผู้ใช้อยู่ในขอบเขต จำเป็นหากตั้งค่า `scopeTag` และต้องว่างเปล่าในกรณีอื่น
`displayName`	string	ไม่	ชื่อที่ Control Panel แสดง ไม่เกิน 64 ตัวอักษร หากไม่ระบุจะแสดง `name`

ตัวอย่างคำขอ

{
  "code": "XXXXX-XXXXX",
  "name": "Q3 holdout",
  "percentage": 10
}

การตอบกลับ

ส่งคืน { "group": { ... } }, ซึ่งเป็น ออบเจ็กต์ Control group ใหม่

Get

ส่งคืน control group หนึ่งกลุ่มตามโค้ด พร้อมด้วยขนาด hold-out, generation และจำนวนผู้ใช้ที่อยู่เบื้องหลัง

GET /api/applications/{code}/control_groups/{control_group_code}

พารามิเตอร์ของเส้นทาง

พารามิเตอร์	ประเภท	คำอธิบาย
`code`	string	โค้ดแอปพลิเคชันที่กลุ่มเป็นของ
`control_group_code`	string	โค้ดของ control group

การตอบกลับ

ฟิลด์	ประเภท	คำอธิบาย
`group`	Control group object	control group ที่ร้องขอ
`total_users`	integer	ผู้ใช้ทั้งหมดในแอปพลิเคชัน
`control_group_users`	integer	ผู้ใช้ที่ถูกกันออกไปในปัจจุบัน
`calculation_status`	string	`TASK_STATUS_NOT_STARTED`, `TASK_STATUS_IN_PROGRESS` หรือ `TASK_STATUS_COMPLETED`
`has_data`	boolean	ว่ามีข้อมูลขนาดที่แคชไว้พร้อมใช้งานแล้วหรือไม่

UpdatePercentage

ตั้งค่าเปอร์เซ็นต์ hold-out (1–20) ของ control group หนึ่ง การปรับขนาดจะคงสมาชิกที่มีอยู่ทั้งหมดไว้: hold-out จะขยายหรือหดตัวรอบๆ สมาชิกเหล่านั้นแทนที่จะถูกสร้างขึ้นใหม่ ถูกแทนที่ด้วย UpdateSettings ซึ่งใช้ขนาด ขอบเขต และโหมดอายุการใช้งานในการเรียกครั้งเดียว แต่ยังคงรองรับอยู่

POST /api/applications/{code}/control_groups/{control_group_code}

Request body

พารามิเตอร์	ประเภท	จำเป็น	คำอธิบาย
`percentage`	integer	ใช่	ขนาด hold-out ใหม่เป็นเปอร์เซ็นต์, 1–20

การตอบกลับ

ออบเจ็กต์ว่างเมื่อสำเร็จ: {}

UpdateCountries

ตั้งค่าประเทศที่ control group หนึ่งถูกกำหนดขอบเขตไว้ การเปลี่ยนขอบเขตจะเริ่มการวัดผล uplift ใหม่ เนื่องจากประชากรที่ถูกเปรียบเทียบมีการเปลี่ยนแปลง hold-out เองจะไม่ถูกสร้างขึ้นใหม่ ถูกแทนที่ด้วย UpdateSettings ซึ่งกำหนดขอบเขตแท็กได้ด้วย แต่ยังคงรองรับอยู่

POST /api/applications/{code}/control_groups/{control_group_code}/countries

Request body

พารามิเตอร์	ประเภท	จำเป็น	คำอธิบาย
`countries`	array of strings	ใช่	รหัสประเทศ ISO-3166-1 alpha-2 ตัวพิมพ์เล็ก รายการที่ว่างเปล่าจะขยายกลุ่มกลับไปเป็นทุกประเทศ รหัสจะไม่คำนึงถึงตัวพิมพ์เล็ก-ใหญ่เมื่อป้อนข้อมูล

ตัวอย่างคำขอ

{
  "countries": ["us", "ca", "gb"]
}

การตอบกลับ

ออบเจ็กต์ว่างเมื่อสำเร็จ: {}

UpdateSettings

ใช้ขนาด ขอบเขตประเทศและแท็ก และโหมดอายุการใช้งานของ control group ในการเรียกครั้งเดียว การเปลี่ยนแปลงที่ส่งผลต่อว่าใครถูกกันออกหรือกันออกนานเท่าใด (ขนาด ขอบเขต โหมด ระยะเวลารีเฟรช หรือวันสิ้นสุด) จะปิดรอบที่กำลังทำงานอยู่และเริ่มรอบใหม่ การส่งค่าปัจจุบันจะไม่เปลี่ยนแปลงอะไร ปฏิเสธ control group ที่เป็นของ hold-out ของแคมเปญเอง เช่นเดียวกับ UpdatePercentage

POST /api/applications/{code}/control_groups/{control_group_code}/settings

Request body

พารามิเตอร์	ประเภท	จำเป็น	คำอธิบาย
`percentage`	integer	ใช่	ขนาด hold-out เป็นเปอร์เซ็นต์, 1–20
`countries`	array of strings	ไม่	รหัสประเทศ ISO-3166-1 alpha-2 ตัวพิมพ์เล็ก รายการที่ว่างเปล่าจะขยายกลุ่มกลับไปเป็นทุกประเทศ
`scopeTag`	string	ไม่	แท็กชนิด string หรือ boolean ที่ใช้กำหนดขอบเขตของ hold-out โดยใช้เงื่อนไข AND ร่วมกับ `countries` หากว่างเปล่าจะลบขอบเขตแท็ก ดู ขอบเขตแท็ก ด้านล่าง
`scopeValues`	array of strings	ดูหมายเหตุ	ค่าของ `scopeTag` ที่ทำให้ผู้ใช้อยู่ในขอบเขต จำเป็นหากตั้งค่า `scopeTag` และต้องว่างเปล่าในกรณีอื่น
`mode`	string	ไม่	อายุการใช้งานของสมาชิก: `CONTROL_GROUP_MODE_PERMANENT` (ค่าเริ่มต้น), `CONTROL_GROUP_MODE_AUTO_REFRESH` หรือ `CONTROL_GROUP_MODE_EXPERIMENT`
`refreshPeriodDays`	integer	ดูหมายเหตุ	จำนวนวันระหว่างการสุ่มใหม่, 7–365 จำเป็นเมื่อใช้ `CONTROL_GROUP_MODE_AUTO_REFRESH` และต้องไม่ระบุในกรณีอื่น
`endsAt`	string (RFC 3339)	ดูหมายเหตุ	เวลาที่การทดลองปิดลง ต้องห่างจากปัจจุบันอย่างน้อย 30 วัน จำเป็นเมื่อใช้ `CONTROL_GROUP_MODE_EXPERIMENT` และต้องไม่ระบุในกรณีอื่น

ทุกฟิลด์จะถูกใช้ตามที่ส่งมา เช่นเดียวกับ UpdateCountries: countries ที่ว่างเปล่าจะขยายกลุ่มกลับไปเป็นทุกประเทศ และ scopeTag ที่ว่างเปล่าจะลบขอบเขตแท็ก

การตอบกลับ

ส่งคืน { "group": { ... } }, ซึ่งเป็น ออบเจ็กต์ Control group ที่อัปเดตแล้ว

ขอบเขตแท็ก (Tag scope)

control group สามารถกันออกเฉพาะผู้ใช้ที่ค่าของแท็กชนิด string หรือ boolean หนึ่งแท็กอยู่ในชุดที่คุณเลือก โดยใช้เงื่อนไข AND ร่วมกับ countries หากตั้งค่าทั้งสองอย่าง ตั้งค่าได้ด้วย Create หรือ UpdateSettings

scopeTag ระบุชื่อแท็ก หากว่างเปล่าหมายถึงไม่มีขอบเขตแท็ก ไม่สามารถเป็น Country ได้: ขอบเขตตามประเทศใช้ countries ไม่ใช่แท็ก
scopeValues ระบุว่าค่าใดของ scopeTag อยู่ในขอบเขต ต้องมีอย่างน้อยหนึ่งค่าเมื่อตั้งค่า scopeTag และห้ามซ้ำกัน ค่าของแท็กชนิด string ต้องไม่เป็นสตริงว่าง ค่าของแท็กชนิด boolean ต้องเป็น "true" หรือ "false" แต่ละค่า
อุปกรณ์ที่ไม่มีค่าสำหรับ scopeTag จะอยู่นอกขอบเขต เช่นเดียวกับอุปกรณ์ที่ไม่มีแท็ก Country
สถานะสมาชิกเองไม่เปลี่ยนแปลง: สูตรที่กำหนดผู้ใช้ไม่ได้รับผลจากขอบเขต ขอบเขตแท็กและประเทศเป็นการตรวจสอบรายอุปกรณ์ที่ทำเพิ่มจากสูตรนั้น โดยจำกัดว่าอุปกรณ์ใดของผู้ใช้ที่ถูกเลือกจะถูกกันออกจริง ไม่ใช่ว่าสูตรเลือกใคร
แท็กระดับผู้ใช้จะถูกคัดลอกไปยังทุกอุปกรณ์ของผู้ใช้นั้นเมื่อตั้งค่า ดังนั้นการตรวจสอบระดับอุปกรณ์ข้างต้นจึงครอบคลุมแท็กระดับผู้ใช้ด้วย ไม่ใช่เฉพาะแท็กระดับอุปกรณ์
การเปลี่ยน scopeTag หรือการเปลี่ยน scopeValues ทั้งชุด (การจัดลำดับใหม่อย่างเดียวไม่นับ) จะปิดรอบที่กำลังทำงานอยู่ด้วย CONTROL_GROUP_CYCLE_CLOSE_REASON_RESCOPED เช่นเดียวกับการเปลี่ยน countries การปิดใช้งานกลุ่มจะคงขอบเขตแท็กไว้ เช่นเดียวกับที่คง countries ไว้

Rename

ตั้งชื่อที่ Control Panel แสดงสำหรับ control group หนึ่ง name เป็นส่วนหนึ่งของคีย์สมาชิกและไม่เปลี่ยนแปลง ดังนั้นกลุ่มจะยังคงมีผู้ใช้เดิมและรอบที่กำลังทำงานอยู่

POST /api/applications/{code}/control_groups/{control_group_code}/display_name

Request body

พารามิเตอร์	ประเภท	จำเป็น	คำอธิบาย
`code`	string	ใช่	โค้ดแอปพลิเคชันที่กลุ่มเป็นของ
`controlGroupCode`	string	ใช่	โค้ดของ control group
`displayName`	string	ไม่	ชื่อใหม่ ไม่เกิน 64 ตัวอักษรและไม่ซ้ำกันภายในแอปพลิเคชัน ส่งสตริงว่างเพื่อให้แสดง `name` อีกครั้ง

การตอบกลับ

ส่งคืน { "group": { ... } }, ซึ่งเป็น ออบเจ็กต์ Control group ที่เปลี่ยนชื่อแล้ว

Disable

ปิดการทำงานของ control group หนึ่ง โดยยังคงรักษากลุ่มและ generation ของมันไว้ เพื่อให้การเปิดใช้งานอีกครั้งจะคืนค่า hold-out เดิมแทนที่จะสร้างกลุ่มใหม่

POST /api/applications/{code}/control_groups/{control_group_code}/disable

การตอบกลับ

ออบเจ็กต์ว่างเมื่อสำเร็จ: {}

Reshuffle

สร้าง hold-out ของ control group หนึ่งขึ้นมาใหม่โดยการเพิ่ม generation นี่เป็นวิธีเดียวที่จะได้กลุ่มตัวอย่างที่แตกต่าง: สถานะสมาชิกถูกกำหนดไว้แล้ว ดังนั้นการปิดและเปิดใช้งานใหม่จะสร้างกลุ่มเดิมที่เหมือนกันทุกประการ

POST /api/applications/{code}/control_groups/{control_group_code}/reshuffle

การตอบกลับ

ฟิลด์	ประเภท	คำอธิบาย
`generation`	integer	generation ของกลุ่มหลังจากการสับเปลี่ยน

ForceUpdateCalculation

เริ่มการนับขนาดของ control group หนึ่งใหม่ ตัวเลขที่แคชไว้ก่อนหน้านี้จะยังคงถูกใช้งานจนกว่าการนับใหม่จะเสร็จสิ้น ตรวจสอบความคืบหน้าจาก GetCalculationStatus

POST /api/applications/{code}/control_groups/{control_group_code}/recalculate

การตอบกลับ

ออบเจ็กต์ว่างเมื่อสำเร็จ: {}

GetCalculationStatus

ตรวจสอบเฉพาะจำนวนผู้ใช้ที่เปลี่ยนแปลงของ control group หนึ่งในขณะที่การคำนวณขนาดกำลังทำงานอยู่

GET /api/applications/{code}/control_groups/{control_group_code}/calculation_status

การตอบกลับ

ฟิลด์	ประเภท	คำอธิบาย
`total_users`	integer	ผู้ใช้ทั้งหมดในแอปพลิเคชัน
`control_group_users`	integer	ผู้ใช้ที่ถูกกันออกไป, นับจากทั้งแอปพลิเคชัน
`calculation_status`	string	`TASK_STATUS_NOT_STARTED`, `TASK_STATUS_IN_PROGRESS` หรือ `TASK_STATUS_COMPLETED`
`has_data`	boolean	ว่ามีข้อมูลขนาดที่แคชไว้พร้อมใช้งานหรือไม่

GetAnalytics

ส่งคืนข้อมูลการวิเคราะห์ Control-vs-Treatment ที่คำนวณไว้ล่วงหน้าสำหรับ control group หนึ่ง

GET /api/applications/{code}/control_groups/{control_group_code}/analytics

พารามิเตอร์ของ Query

พารามิเตอร์	ประเภท	จำเป็น	คำอธิบาย
`windowDays`	string	ไม่	ค่าที่ตั้งไว้ล่วงหน้าสำหรับหน้าต่างย้อนหลัง: `WINDOW_DAYS_3`, `WINDOW_DAYS_7` หรือ `WINDOW_DAYS_30`

การตอบกลับ

ฟิลด์	ประเภท	คำอธิบาย
`events`	array of objects	หนึ่งรายการต่อ event ที่ติดตาม, แต่ละรายการมี `event`, `treatment` และ `control` (`users`, `conversions`, `conversion_rate`, `events_per_user`), `uplift_pct`, `incremental_events`, `percent_of_treatment`, `z_score`, `p_value`, `confidence_pct` และ `significance` (`SIGNIFICANCE_NOT_ENOUGH_DATA`, `SIGNIFICANCE_NOT_SIGNIFICANT` หรือ `SIGNIFICANCE_SIGNIFICANT`)

ListControlGroupCycles

แสดงรายการรอบที่ปิดแล้วของ control group หนึ่ง เรียงจากใหม่สุดไปเก่าสุด แต่ละรอบคือสมาชิกที่กลุ่มทำงานด้วยระหว่างการเปลี่ยนการตั้งค่าสองครั้ง พร้อมการตั้งค่าที่ใช้สร้างสมาชิกนั้น รอบที่กำลังทำงานอยู่ (ปัจจุบัน) จะไม่อยู่ในรายการนี้ การตั้งค่าของรอบนั้นอยู่บน ออบเจ็กต์ Control group เอง

GET /api/applications/{code}/control_groups/{control_group_code}/cycles

การตอบกลับ

ฟิลด์	ประเภท	คำอธิบาย
`cycles`	array of Control group cycle objects	เรียงจากใหม่สุดไปเก่าสุด

ออบเจ็กต์ Control group cycle

ฟิลด์	ประเภท	คำอธิบาย
`cycle_number`	integer	เรียงลำดับต่อเนื่องภายในกลุ่ม; `cycle_number` ของกลุ่มเองคือหมายเลขถัดจากรอบสุดท้ายที่ปิดไปในรายการนี้
`mode`	string	โหมดอายุการใช้งานที่กลุ่มทำงานอยู่ในรอบนี้: `CONTROL_GROUP_MODE_PERMANENT`, `CONTROL_GROUP_MODE_AUTO_REFRESH` หรือ `CONTROL_GROUP_MODE_EXPERIMENT`
`generation`	integer	generation ของกลุ่มในรอบนี้
`percentage`	integer	ขนาด hold-out ในรอบนี้
`countries`	array of strings	ขอบเขตประเทศในรอบนี้; หากว่างเปล่าหมายถึงทุกประเทศ
`started_at` / `ended_at`	string (RFC 3339)	ช่วงเวลาที่รอบนี้ทำงาน
`close_reason`	string	เหตุผลที่รอบสิ้นสุด: `CONTROL_GROUP_CYCLE_CLOSE_REASON_ROLLOVER`, `_EXPIRED`, `_RESHUFFLED`, `_RESIZED`, `_RESCOPED`, `_MODE_CHANGED` หรือ `_DISABLED`
`scope_tag`	string	แท็กที่ hold-out ของรอบนี้ถูกกำหนดขอบเขตไว้ โดยใช้เงื่อนไข AND ร่วมกับ `countries` ว่างเปล่าหากไม่มีขอบเขตแท็ก และสำหรับทุกรอบที่ปิดก่อนที่ขอบเขตแท็กจะมีอยู่ แม้ว่ากลุ่มจะมีขอบเขตแท็กในภายหลังก็ตาม
`scope_values`	array of strings	ค่าของ `scope_tag` ที่ทำให้ผู้ใช้อยู่ในขอบเขตในรอบนี้; ตั้งค่าเฉพาะเมื่อมี `scope_tag` ด้วย

CheckControlGroupMembership

รายงานสำหรับแต่ละ User ID ว่าถูกกันออกไปโดย control group หนึ่งในขณะนี้หรือไม่ สถานะสมาชิกจะคำนวณจาก ID เพียงอย่างเดียว ไม่มีการอ่านบันทึกผู้ใช้ ดังนั้น ID ที่แอปพลิเคชันไม่เคยเห็นก็จะถูกตอบด้วย และกลุ่มที่ถูกปิดใช้งานจะตอบ false สำหรับทุก ID แทนที่จะเป็นข้อผิดพลาด กลุ่มที่มีขอบเขตประเทศหรือแท็กจะกันผู้ใช้ออกก็ต่อเมื่ออุปกรณ์ใดอุปกรณ์หนึ่งของผู้ใช้อยู่ในขอบเขตนั้น ดังนั้น ID ที่ไม่เคยเห็น (ไม่มีอุปกรณ์เลย) จะตอบ false ที่นั่น ทั้งที่ ID เดียวกันจะตอบ true ในกลุ่มที่ไม่มีขอบเขต ใช้วิธีนี้แทนการส่งออกทั้งกลุ่มเพื่อตรวจสอบผู้ใช้ของการส่งหรือการนำเข้าที่เฉพาะเจาะจง

POST /api/applications/{code}/control_groups/{control_group_code}/membership

Request body

พารามิเตอร์	ประเภท	จำเป็น	คำอธิบาย
`userIds`	array of strings	ใช่	User ID ที่จะตรวจสอบ, ไม่เกิน 1,000 รายการต่อการเรียก

ตัวอย่างคำขอ

{
  "userIds": ["user-1", "user-2", "user-3"]
}

การตอบกลับ

ฟิลด์	ประเภท	คำอธิบาย
`users`	array of objects	หนึ่งรายการต่อ ID ที่ร้องขอ, ตามลำดับที่ให้มา (รวมรายการที่ซ้ำกัน) แต่ละรายการมี `user_id` (string) และ `in_control_group` (boolean)

ตัวอย่างการตอบกลับ

{
  "users": [
    { "user_id": "user-1", "in_control_group": false },
    { "user_id": "user-2", "in_control_group": true },
    { "user_id": "user-3", "in_control_group": false }
  ]
}

Delete

ลบ control group ออกไปทั้งหมด กลุ่มจะหยุดกันผู้ใช้ออก และไม่สามารถเปิดดูสถิติของกลุ่มได้อีก กลุ่มอื่นของแอปพลิเคชันยังคงทำงานต่อไป

DELETE /api/applications/{code}/control_groups/{control_group_code}

การตอบกลับ

ออบเจ็กต์ว่างเมื่อสำเร็จ: {}

ออบเจ็กต์ Control group

ฟิลด์	ประเภท	คำอธิบาย
`code`	string	โค้ด Control group (รูปแบบ `XXXXX-XXXXX`), จะคงที่ตลอดอายุของกลุ่ม
`name`	string	ชื่อกลุ่ม ซึ่งเป็นส่วนหนึ่งของคีย์สมาชิก หากว่างเปล่าหมายถึงกลุ่มดั้งเดิมของแอปพลิเคชันที่ไม่มีชื่อ
`display_name`	string	ชื่อที่ Control Panel แสดง หากว่างเปล่าจะแสดง `name` และกลุ่มที่ไม่มีชื่อจะแสดงเป็น Global
`segment`	string	นิพจน์ Seglang ที่ใช้วัดผลกลุ่ม; หากว่างเปล่าหมายถึงฐานผู้ใช้ทั้งหมด
`percentage`	integer	ขนาด hold-out เป็นเปอร์เซ็นต์, 1–20 ศูนย์หมายถึงกลุ่มถูกปิดใช้งาน
`enabled`	boolean	ว่ากลุ่มกำลังกันผู้ใช้ออกไปในปัจจุบันหรือไม่
`generation`	integer	เพิ่มขึ้นทุกครั้งที่มีการสับเปลี่ยน; `0` หมายถึงไม่เคยถูกสับเปลี่ยน
`last_modified_at`	string (RFC 3339)	เวลาที่การตั้งค่าของกลุ่มถูกเปลี่ยนแปลงล่าสุด
`last_modified_by`	string	อีเมลของผู้ใช้ที่เปลี่ยนแปลงกลุ่มล่าสุด
`application_id`	integer	ID ตัวเลขของแอปพลิเคชัน, ส่วนแรกของคีย์สมาชิก `<application_id>:<generation>:<name>:<user_id>` ที่ CheckControlGroupMembership ใช้แฮชเพื่อตัดสินว่าผู้ใช้ถูกกันออกไปหรือไม่
`countries`	array of strings	รหัสประเทศ ISO-3166-1 alpha-2 ตัวพิมพ์เล็กที่ hold-out ถูกกำหนดขอบเขตไว้ หากว่างเปล่าหมายถึงทุกประเทศ
`scope_tag`	string	แท็กที่ hold-out ถูกกำหนดขอบเขตไว้ โดยใช้เงื่อนไข AND ร่วมกับ `countries` หากว่างเปล่าหมายถึงไม่มีขอบเขตแท็ก ดู ขอบเขตแท็ก
`scope_values`	array of strings	ค่าของ `scope_tag` ที่ทำให้ผู้ใช้อยู่ในขอบเขต แท็กชนิด boolean ใช้ `"true"` และ `"false"`

ที่เกี่ยวข้อง

Control groups (คู่มือผลิตภัณฑ์)

Segmentation (Filters) API