API การแบ่งส่วน (ฟิลเตอร์)

createFilter

POST https://api.pushwoosh.com/json/1.3/createFilter

สร้างฟิลเตอร์ใหม่

เนื้อหาของคำขอ

ชื่อ	จำเป็น	ประเภท	คำอธิบาย
auth*	ใช่	string	API access token จาก Pushwoosh Control Panel
name*	ใช่	string	ชื่อฟิลเตอร์
filter_expression*	ใช่	string	นิพจน์ที่สร้างขึ้นตามกฎของ ภาษาการแบ่งส่วน ตัวอย่าง: T(“City”, eq, “Madrid”) เพื่อแบ่งส่วนผู้ใช้ที่เมืองคือมาดริด
application	ไม่	string	รหัสแอปพลิเคชัน Pushwoosh ที่จำกัดขอบเขตตัวกรองไว้ที่แอปหนึ่ง เมื่อกำหนดค่า High-speed delivery แล้ว การใช้พารามิเตอร์นี้จะสร้างตัวกรองความเร็วสูง หากไม่ได้กำหนดค่าไว้ การใช้พารามิเตอร์นี้จะสร้างตัวกรองที่จำกัดขอบเขตในแอปแบบปกติ หากบัญชีของคุณต้องใช้ตัวกรองที่จำกัดขอบเขตในแอป มิฉะนั้น คำขอจะส่งคืนข้อผิดพลาด 403: the application parameter creates a High-Speed Delivery filter, and High-Speed Delivery is not enabled for this account ให้เว้นพารามิเตอร์นี้ไว้ เว้นแต่กรณีใดกรณีหนึ่งข้างต้นจะตรงกับคุณ
expiration_date	ไม่	string	วันหมดอายุของฟิลเตอร์ ฟิลเตอร์จะถูกลบโดยอัตโนมัติในวันที่ระบุ เว้นแต่จะถูกใช้ใน Preset หรือ RSS Feed

200

{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "name": "filter name"
  }
}

ตัวอย่าง

{
  "request": {
    "auth": "yxoPUlwqm…………pIyEX4H",
    "name": "City = Madrid",
    "filter_expression": "T(\"City\", eq, \"Madrid\")",
    "application": "B18XX-XXXXX",
    "expiration_date": "2025-01-01"
  }
}

// การสร้างฟิลเตอร์สำหรับโซนเวลา
{
  "request": {
    "auth": "yxoPUlwqm…………pIyEX4H", // API access token จาก Pushwoosh Control Panel
    "name": "Timezone Filter",
    "filter_expression": "T(\"Timezone\", BETWEEN, [\"UTC-12:00\", \"UTC+14:00\"])"
  }
}

listFilters

POST https://api.pushwoosh.com/json/1.3/listFilters

ส่งคืนรายการเซกเมนต์ (ฟิลเตอร์) ที่มีอยู่พร้อมเงื่อนไข

เนื้อหาของคำขอ

ชื่อ	จำเป็น	ประเภท	คำอธิบาย
auth*	ใช่	string	API access token จาก Pushwoosh Control Panel
application*	ใช่	string	รหัสแอปพลิเคชัน Pushwoosh

200

{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "filters": [{
      "code": "52551-F2F42",
      "name": "City = Madrid",
      "filter_expression": "T(\"City\", eq, \"madrid\")",
      "expiration_date": "2025-01-01",
      "application": "B18XX-XXXXX"
    }]
  }
}

ตัวอย่าง

{
  "request": {
    "auth": "yxoPUlwqm…………pIyEX4H",
    "application": "B18XX-XXXXX"
  }
}

deleteFilter

POST https://api.pushwoosh.com/json/1.3/deleteFilter

ลบฟิลเตอร์ที่มีอยู่

เนื้อหาของคำขอ

ชื่อ	ประเภท	คำอธิบาย
auth*	string	API access token จาก Pushwoosh Control Panel
name*	string	ชื่อฟิลเตอร์

200

{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}

ตัวอย่าง

{
  "request": {
    "auth": "yxoPUlwqm…………pIyEX4H", // API access token จาก Pushwoosh Control Panel
    "name": "filter name"
  }
}

exportSegment

POST https://api.pushwoosh.com/api/v2/audience/exportSegment

คำขอที่ตั้งเวลาไว้ ส่งออกรายชื่อผู้สมัครสมาชิกที่เข้าเงื่อนไขฟิลเตอร์ที่ระบุ

เนื้อหาของคำขอ

ชื่อ	จำเป็น	ประเภท	คำอธิบาย
auth*	ใช่	string	API access token จาก Pushwoosh Control Panel
filterExpression*	ใช่	string	เงื่อนไขฟิลเตอร์
exportData	ไม่	array	ข้อมูลที่จะส่งออก ค่าที่เป็นไปได้: "hwids", "push_tokens", "users", "tags", "location", "ad_identifiers" การรวม "location" จะเพิ่มคอลัมน์ Latitude และ Longitude ไปยัง CSV ที่ส่งออก หาก exportData ถูกละไว้ Latitude และ Longitude จะถูกรวมอยู่ในการส่งออกโดยค่าเริ่มต้น "ad_identifiers" จะเพิ่มคอลัมน์ MADID, Email SHA256 และ Phone SHA256 สำหรับการสร้างไฟล์ต้นฉบับ Google Customer Match หรือ Meta Custom Audience — ดูหมายเหตุ การส่งออกตัวระบุโฆษณา ด้านล่าง
filterCode	ไม่	string	รหัสฟิลเตอร์ ที่สร้างไว้ล่วงหน้า สามารถใช้แทน filterExpression ได้ สามารถรับได้จาก /listFilters API หรือแถบที่อยู่ของเบราว์เซอร์ของคุณเมื่อดูฟิลเตอร์ใน Control Panel
applicationCode	จำเป็นหากคุณใช้ filterExpression หรือ filterCode	string	รหัสแอปพลิเคชัน Pushwoosh
generateExport	ไม่	boolean	โดยค่าเริ่มต้นตั้งค่าเป็น true และการตอบกลับจะมีลิงก์สำหรับดาวน์โหลดไฟล์ หากเป็น false จะมีการส่งเฉพาะจำนวนอุปกรณ์ในการตอบกลับ
format	ไม่	string	ตั้งค่ารูปแบบของไฟล์ที่ส่งออก: “csv” หรือ “json_each_line” หากไม่ระบุ จะสร้างไฟล์ CSV
tagsList	ไม่	array	ระบุ tags ที่จะส่งออก หากต้องการรับเฉพาะแท็กที่ระบุ อาร์เรย์ “exportData” ควรมีค่า “tags”
includeWithoutTokens	ไม่	boolean	ตั้งค่าเป็น true เพื่อรวมผู้ใช้ที่ไม่มี push token ในไฟล์ที่ส่งออก ค่าเริ่มต้นคือ false

200 สำเร็จ

{
  "task_id": "177458"
}

ตัวอย่าง

{
  "auth": "yxoPUlwqm…………pIyEX4H",                           // จำเป็น API access token จาก Pushwoosh Control Panel
  "filterExpression": "AT(\"12345-67890\", \"Name\", any)", // เงื่อนไขฟิลเตอร์ โปรดดูคู่มือภาษาการแบ่งส่วนสำหรับไวยากรณ์
  "filterCode": "12345-67890",                              // รหัสฟิลเตอร์ที่สร้างไว้ล่วงหน้า สามารถใช้แทน filterExpression ได้
  "applicationCode": "00000-AAAAA",                         // จำเป็นหากคุณใช้ `filterExpression` หรือ `filterCode` รหัสแอป Pushwoosh สามารถรับได้จากคำขอ /listFilters API หรือแถบที่อยู่ของเบราว์เซอร์ของคุณขณะดูฟิลเตอร์ใน Control Panel
  "generateExport": true,                                   // หากเป็น false จะมีการส่งเฉพาะจำนวนอุปกรณ์ในการตอบกลับ โดยค่าเริ่มต้น การตอบกลับจะมีลิงก์สำหรับดาวน์โหลดไฟล์ CSV
  "format": "json_each_line",                               // รูปแบบของไฟล์ที่จะนำเสนอข้อมูล: "csv" – ดาวน์โหลดไฟล์ .csv; "json" – ไฟล์ JSON ที่มีอุปกรณ์ที่ส่งออกทั้งหมด; หรือ "json_each_line" – JSON หนึ่งบรรทัดสำหรับแต่ละอุปกรณ์ หากไม่ระบุ CSV จะเป็นรูปแบบเริ่มต้น
  "exportData": ["hwids", "tags"],                          // ไม่บังคับ ข้อมูลที่จะส่งออก ค่าที่เป็นไปได้: "hwids", "push_tokens", "users", "tags", "location", "fcm_keys", "web keys", "ad_identifiers"
  "tagsList": ["Name", "Level"],                            // ไม่บังคับ ระบุแท็กที่จะส่งออก หากต้องการรับเฉพาะแท็กที่ระบุ ควรส่งค่า "tags" ภายในอาร์เรย์ "exportData" หรือ "exportData" ควรว่างเปล่า
  "includeWithoutTokens": true                              // ไม่บังคับ ตั้งค่าเป็น true เพื่อรวมผู้ใช้ที่ไม่มี push token ในไฟล์ที่ส่งออก ค่าเริ่มต้นคือ false
}

หมายเหตุ

โปรดดูการอ้างอิงภาษาการแบ่งส่วนสำหรับการเขียนนิพจน์ฟิลเตอร์ได้ ที่นี่

ตัวอย่างเช่น หากต้องการส่งออกผู้สมัครสมาชิกทั้งหมดของแอปใดแอปหนึ่ง ให้ใช้เงื่อนไขฟิลเตอร์ต่อไปนี้:

{
  "auth": "yxoPUlwqm…………pIyEX4H",            // API access token จาก Pushwoosh Control Panel
  "filterExpression": "A(\"AAAAA-BBBBB\")",  // นิพจน์ฟิลเตอร์ที่อ้างอิงถึงเซกเมนต์ของแอป
  "applicationCode": "AAAAA-BBBBB"           // รหัสแอป Pushwoosh ที่จำเป็น
}

ข้อควรระวัง

ในการตอบกลับ คุณจะได้รับ task_id เพื่อใช้รับไฟล์ผลลัพธ์ จากนั้น เรียกใช้ /exportSegment/result พร้อมกับ task_id นั้นในเนื้อหาคำขอเพื่อดึงไฟล์ผลลัพธ์

ผลลัพธ์ของ exportSegment

POST https://api.pushwoosh.com/api/v2/audience/exportSegment/result

ดึงลิงก์ไปยังไฟล์ CSV ที่มีผลลัพธ์ของ /exportSegment

เนื้อหาของคำขอ

ชื่อ	ประเภท	คำอธิบาย
auth*	String	API access token จาก Pushwoosh Control Panel
task_id*	String	ตัวระบุที่ได้รับในการตอบกลับ /exportSegment ของคุณ

200: OK

{
  "devicesCount": "24735",
  "filename": "https://static.pushwoosh.com/segment-export/export_segment_XXXXX_XXXXX_xxxxxxxxxxxxxxxxx.csv.zip",
  "status": "completed"
}

ส่ง “task_id” ที่ได้รับในการตอบกลับ /exportSegment ของคุณในเนื้อหาคำขอ /exportSegment/result

ในการตอบกลับ /exportSegment/result คุณจะได้รับพารามิเตอร์ “filename” ไปตามลิงก์ที่ให้ไว้ในค่าพารามิเตอร์นั้นเพื่อดาวน์โหลดไฟล์ ZIP โดยอัตโนมัติ แตกไฟล์เพื่อดึงไฟล์ CSV หรือ JSON (ขึ้นอยู่กับ “format” ที่ระบุในคำขอของคุณ) ที่มีข้อมูลของอุปกรณ์

ตั้งแต่วันที่ 3 เมษายน 2025 เป็นต้นไป จำเป็นต้องมีการอนุญาตเพื่อดาวน์โหลดไฟล์:

• หากดาวน์โหลดผ่าน เบราว์เซอร์ เพียงเข้าสู่ระบบ Pushwoosh Control Panel เพื่อเข้าถึง
• หากดาวน์โหลดผ่าน ซอฟต์แวร์เซิร์ฟเวอร์ ให้ใส่ส่วนหัวต่อไปนี้ในคำขอของคุณ: Authorization: Token YOUR_API_TOKEN

หากคุณระบุ “exportData” ในคำขอ /exportSegment ของคุณ ไฟล์ที่ดาวน์โหลดจะมีเฉพาะข้อมูลที่ร้องขอ โดยค่าเริ่มต้น ไฟล์จะมีข้อมูลผู้ใช้ดังต่อไปนี้:

ฟิลด์	คำอธิบาย	ตัวอย่างค่า
Hwid	Hardware ID ของอุปกรณ์	01D1BA5C-AAAA-0000-BBBB-9B81CD5823C8
User ID	User ID ที่เชื่อมโยงอุปกรณ์กับผู้ใช้รายใดรายหนึ่ง หากไม่มีการกำหนด User ID จะใช้ HWID แทน	user8192
Push Token	ตัวระบุที่ไม่ซ้ำกันซึ่งกำหนดให้กับอุปกรณ์โดยเกตเวย์การส่งข้อความบนคลาวด์ เรียนรู้เพิ่มเติม	eeeb2fd7…0fc3547
Type	ประเภทแพลตฟอร์ม (จำนวนเต็ม)	1
Type (humanized)	ประเภทแพลตฟอร์ม (สตริง)	iOS
Age	ค่าของแท็ก Age เริ่มต้น	29
ApplicationVersion	ค่าของแท็ก Application Version เริ่มต้น	1.12.0.0
City	ค่าของแท็ก City เริ่มต้น	us, boston
TagName	ค่าของแท็กที่สร้างขึ้นในบัญชีของคุณ	TagValue

การส่งออกตัวระบุโฆษณา

เพิ่ม "ad_identifiers" ไปยัง exportData เพื่อรับไฟล์ที่จัดรูปแบบสำหรับอัปโหลดโดยตรงเป็นแหล่งข้อมูล Google Customer Match หรือ Meta Custom Audience ค่านี้เป็นแบบเลือกใช้เท่านั้น — จะไม่ถูกรวมไว้โดยค่าเริ่มต้น แม้ว่าจะไม่ได้ระบุ exportData ก็ตาม จะมีผลเฉพาะเมื่อ format ถูกตั้งค่าเป็น "csv" เท่านั้น การร้องขอด้วย "json" หรือ "json_each_line" จะไม่ส่งคืนข้อผิดพลาด แต่คอลัมน์ด้านล่างจะถูกละเว้นจากรูปแบบเหล่านั้นอย่างเงียบๆ

ฟิลด์	คำอธิบาย
MADID	รหัสโฆษณาบนมือถือ (GAID หรือ IDFA) ซึ่งทำให้เป็นตัวพิมพ์เล็ก
Email SHA256	แฮช SHA-256 ของอีเมลผู้ใช้ ซึ่งทำให้เป็นตัวพิมพ์เล็กและตัดช่องว่างก่อนการแฮช
Phone SHA256	แฮช SHA-256 ของหมายเลขโทรศัพท์ของผู้ใช้ในรูปแบบ E.164 ก่อนการแฮช

แถวสำหรับผู้ใช้ที่ไม่มีตัวระบุทั้งสามจะยังคงถูกส่งออก โดยคอลัมน์ MADID, Email SHA256 และ Phone SHA256 จะถูกเว้นว่างไว้

ส่งออกกิจกรรมแอปของผู้ใช้แต่ละราย

หมายเหตุ

สถิติแคมเปญ ส่งคืนจำนวนการเปิด/ส่งที่รวบรวมตามชั่วโมงและแพลตฟอร์ม ไม่มีคอลัมน์ hwid หรือ user_id หากต้องการดูว่าผู้ใช้รายใดเปิดแอปและเมื่อใด ให้ส่งออกเซกเมนต์ที่สร้างขึ้นจากเหตุการณ์ PW_ApplicationOpen แทน

PW_ApplicationOpen ใช้สำหรับมือถือเท่านั้น สำหรับโปรเจกต์เว็บ การส่งออกเซกเมนต์จะไม่มีแถวข้อมูล เนื่องจากเหตุการณ์นี้ไม่เคยเกิดขึ้นที่นั่น

1. สร้างนิพจน์ฟิลเตอร์จากเหตุการณ์ PW_ApplicationOpen โดยกำหนดขอบเขตตามช่วงเวลาที่คุณต้องการ ใช้ ตัวดำเนินการวันที่ของเหตุการณ์ ตัวอย่างเช่น “เปิดเมื่อวานนี้”:

Event("AAAAA-BBBBB", "PW_ApplicationOpen", date daysago eq 1)

2. เรียกใช้ /exportSegment พร้อมกับ filterExpression, applicationCode และ exportData: ["hwids", "users"]
3. เรียกใช้ /exportSegment/result พร้อมกับ task_id ที่ส่งคืนมาเพื่อดาวน์โหลดไฟล์ CSV ที่มีคอลัมน์ Hwid และ User ID สำหรับทุกอุปกรณ์ที่เปิดแอปในช่วงเวลานั้น

ข้อควรระวัง

User ID จะเก็บตัวระบุใดๆ ที่คุณกำหนดให้กับอุปกรณ์ หากคุณไม่ได้กำหนด มันจะใช้ HWID แทน การส่งออกจะบอกคุณว่าใครเปิดแอปในช่วงเวลาที่กรองไว้ มันไม่ใช่บันทึกเหตุการณ์การเปิดแต่ละครั้งที่มีคอลัมน์ประทับเวลา ดังนั้นให้สร้างหนึ่งเซกเมนต์ต่อวัน (หรือต่อช่วงเวลา) หากคุณต้องการความละเอียดระดับวันต่อวัน