ข้ามไปยังเนื้อหา
เอกสารสำหรับนักพัฒนา คู่มือวิธีการ การสนับสนุน ขอสาธิต เข้าสู่ระบบ
Pushwoosh.com

Live Activity

Live Activity คือการ์ดที่อัปเดตแบบเรียลไทม์ เพื่อให้ผู้ใช้เห็นความคืบหน้าโดยไม่ต้องเปิดแอป (สถานะเที่ยวบิน การจัดส่ง การเดินทาง และอื่นๆ ที่คล้ายกัน) บน iOS จะเป็นการ์ดขนาดเล็กบนหน้าจอล็อกและ Dynamic Island บน Android 16 ขึ้นไป จะเป็นการ์ดประเภทเดียวกันที่แสดงเป็นการแจ้งเตือนต่อเนื่องพร้อมแถบความคืบหน้า

ใช้องค์ประกอบ Live Activity ใน journey เพื่อเริ่ม อัปเดต หรือสิ้นสุดการ์ดนั้น บน iOS, Android หรือทั้งสองแพลตฟอร์ม

แต่ละองค์ประกอบทำหนึ่งการกระทำ:

  • Start: สร้างการ์ด
  • Update: เปลี่ยนแปลงการ์ดที่มีอยู่
  • End: ปิดการ์ด

หากต้องการเปลี่ยนแปลงหรือปิดการ์ดเดียวกันในภายหลัง ให้เพิ่มองค์ประกอบ Live Activity อีกอันหนึ่งและชี้กลับไปที่องค์ประกอบที่สร้างการ์ดนั้นด้วย Card created by

ตัวอย่างกรณีการใช้งาน

Anchor link to

ใช้องค์ประกอบนี้เมื่อใดก็ตามที่ผู้ใช้ควรเห็นสถานะที่เปลี่ยนแปลงอยู่ตลอด โดยไม่ต้องเปิดแอป

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

ข้อกำหนดเบื้องต้น

Anchor link to

ก่อนตั้งค่าองค์ประกอบนี้ ให้ตรวจสอบสิ่งที่แต่ละแพลตฟอร์มต้องการ

สำหรับการ์ด iOS:

  • การรองรับ iOS Live Activity: แอปของคุณต้องรองรับ Live Activities ดู คู่มือ Live Activities ของ iOS SDK
  • Widget schema ที่เผยแพร่แล้ว: ขอให้ทีมพัฒนาของคุณเผยแพร่ schema ที่ตรงกับประเภท Live Activity ในแอปภายใต้ Applications → Configure → Live Activity schemas พวกเขายังสามารถ เผยแพร่ผ่าน API ได้ สำหรับสิ่งที่ควรอยู่ใน schema ดู การเขียน schema
  • Widget ในรายการ: หลังจาก schema เผยแพร่แล้ว ให้เลือกภายใต้ Widget ในองค์ประกอบนี้ หากรายการ Widget ว่างเปล่า แสดงว่ายังไม่ได้เผยแพร่ schema

สำหรับการแจ้งเตือน Android:

  • การรองรับ Android Live Updates: แอปของคุณต้องใช้ SDK 6.11+ และโมดูล pushwoosh-liveupdates Android ไม่ต้องใช้ schema ขอให้นักพัฒนา Android ของคุณยืนยันว่าโมดูลนี้อยู่ในบิลด์แล้ว

ตั้งค่าองค์ประกอบ

Anchor link to

  1. ลากองค์ประกอบ Live Activity ไปยังผืนผ้าใบ

    รายการ Live Activity ถูกไฮไลต์ในรายการองค์ประกอบช่องทาง

  2. ดับเบิลคลิกที่องค์ประกอบเพื่อเปิดการตั้งค่า

  3. ป้อนชื่อใน Step name

  4. ใน Action ให้เลือกหนึ่งในตัวเลือกต่อไปนี้:

    • Start: สร้างการ์ด Live Activity
    • Update: เปลี่ยนแปลงเนื้อหาของการ์ดที่มีอยู่
    • End: ปิดการ์ด

  5. ภายใต้ Platforms ให้เปิด iOS Live Activity, Android Live Updates หรือทั้งสองอย่าง ต้องเปิดไว้อย่างน้อยหนึ่งแพลตฟอร์ม คุณจึงไม่สามารถปิดแพลตฟอร์มสุดท้ายได้ ใน Update และ End ส่วน Platforms จะแสดงแพลตฟอร์มจากองค์ประกอบ Start ที่เชื่อมโยงและเป็นแบบอ่านอย่างเดียว

    Action ตั้งเป็น Start โดยเปิดทั้ง iOS Live Activity และ Android Live Updates ภายใต้ Platforms

  6. เฉพาะใน Start ให้ตั้งค่าคีย์ของการ์ดเพื่อให้ขั้นตอน Update และ End ในภายหลังสามารถค้นหาการ์ดนี้ได้:

    • ใน Card key: event ให้เลือกอีเวนต์ที่ระบุการ์ด (เช่น อีเวนต์การเข้า journey)
    • ใน Card key: attribute ให้เลือกแอตทริบิวต์ที่ทำให้คีย์ไม่ซ้ำกันต่อผู้เดินทางแต่ละคน สิ่งนี้จำเป็นเมื่อคุณตั้งค่า Card key: event แล้ว หากปล่อยไว้ไม่ตั้งค่าจะทำให้การเลือกอีเวนต์ไม่มีผล เหมือนกับการปล่อยทั้งสองฟิลด์ว่างเปล่า: การ์ดหนึ่งใบต่อผู้เดินทางหนึ่งคน โดยระบุที่อยู่ด้วย user ID เริ่มต้น

    ฟิลด์ Card key: event และ Card key: attribute บนองค์ประกอบ Start

เชื่อมโยง Update และ End กับการ์ดที่ถูกต้อง

Anchor link to

เมื่อ Action เป็น Update หรือ End ให้ใช้ Card created by เพื่อชี้ไปยังองค์ประกอบ Start ที่แน่ชัดซึ่งสร้างการ์ดนี้ขึ้นมา มิฉะนั้น Update หรือ End จะไม่สามารถเข้าถึงได้

  1. ใน Card created by ให้เลือก Step name ขององค์ประกอบ Start นั้น (เช่น Order card start)

หลังจากที่คุณเลือก Card created by แล้ว Card key (from the start element) จะแสดงค่า Card key: event และ Card key: attribute จาก Start นั้น เป็นแบบอ่านอย่างเดียวและยืนยันว่านี่ชี้ไปยังการ์ดใด

องค์ประกอบ Update แสดง Card created by และ Card key แบบอ่านอย่างเดียวที่สืบทอดจาก Start ที่เชื่อมโยง

เลือกภาษาของการ์ด

Anchor link to

Card language ใช้กับทั้งการ์ด iOS และการแจ้งเตือน Android

ตั้งค่า Card language เป็น default หรือรหัสภาษาที่ระบุ เนื้อหาภายใต้ default เป็นค่าสำรองสำหรับภาษาใดก็ตามที่คุณไม่ได้กรอกแยกต่างหาก

ตั้งค่าการ์ด iOS

Anchor link to

ข้ามส่วนนี้หากเปิดเฉพาะ Android Live Updates

เลือก widget และ schema version

Anchor link to

  1. ใน Widget ให้เลือกประเภท Live Activity ที่เผยแพร่แล้วสำหรับการ์ดนี้ ฟิลด์เนื้อหาด้านล่างมาจากตัวเลือกนี้ เมื่อเป็น Update หรือ End ฟิลด์ Widget จะเป็นแบบอ่านอย่างเดียว สืบทอดมาจากองค์ประกอบ Card created by

  2. ใน Schema version ให้เลือกว่าจะใช้ schema ของ widget นั้นเวอร์ชันที่เผยแพร่แล้วเวอร์ชันใด ฟิลด์ Card content มาจากเวอร์ชันนี้ ใน Update และ End ฟิลด์ Schema version ยังคงเป็นตัวเลือกที่ปรับได้: คุณสามารถเลือกเวอร์ชันที่เผยแพร่แล้วอื่นของ widget ที่สืบทอดมาเดียวกันซึ่งแตกต่างจากที่ Start ที่เชื่อมโยงใช้

    ฟิลด์ Widget และ Schema version บนองค์ประกอบ Start

ตั้งค่าแอตทริบิวต์คงที่ของการ์ด (เฉพาะ Start)

Anchor link to

ใน Start ภายใต้ Card attributes ให้เพิ่มฟิลด์ที่คงที่ตลอดอายุการใช้งานของการ์ด ตั้งค่าเพียงครั้งเดียวและไม่เปลี่ยนแปลงอีก เช่น หมายเลขเที่ยวบินหรือ ID คำสั่งซื้อ สิ่งเหล่านี้แยกจากฟิลด์ Card content ด้านล่าง ค่าเหล่านั้นสามารถเปลี่ยนแปลงได้ใน Update

ขอรายการ Field name ที่แน่นอนจากนักพัฒนา iOS ของคุณ ชื่อเหล่านั้นคงที่ตลอดอายุการใช้งานของการ์ด (ActivityAttributes ของแอป) อย่าใช้ชื่อ Card content ที่เปลี่ยนแปลง (ContentState ของแอป)

  1. คลิก Add attribute
  2. ตั้งค่า Field name และ Value สำหรับแต่ละแอตทริบิวต์ที่คุณต้องการ

Update และ End ไม่ได้ตั้งค่าแอตทริบิวต์ สิ่งที่ Start ตั้งค่าไว้สำหรับการ์ดนี้จะคงที่

กรอกเนื้อหาการ์ด

Anchor link to

ภายใต้ Card content ให้พิมพ์ค่าตามตัวอักษรหรือ placeholder การปรับให้เป็นส่วนตัวลงในแต่ละฟิลด์ จะมีหนึ่งฟิลด์ปรากฏต่อหนึ่งพร็อพเพอร์ตี้ใน schema เวอร์ชันที่เลือก

Card language ตั้งเป็น default และฟิลด์ Card content gate, status และ estimatedTime กรอกแล้วสำหรับองค์ประกอบ Start

การกรอกล่วงหน้าใน Update และ End

Anchor link to

ใน Update หรือ End หาก Card content สำหรับ Card language ปัจจุบันว่างเปล่า (รวมถึงภาษาที่คุณเพิ่งเพิ่ม) Pushwoosh จะกรอกฟิลด์ล่วงหน้าจากองค์ประกอบ Start ที่เชื่อมโยงเมื่อคุณเปิดการตั้งค่า:

  • ภาษาเดียวกับ Start หากภาษานั้นมีเนื้อหา
  • หากไม่มี ใช้เนื้อหา default ของ Start
  • หาก Start ไม่มีทั้งสองอย่าง ให้ปล่อยฟิลด์ว่างไว้และกรอกเอง

ค่าที่กรอกล่วงหน้ายังคงแก้ไขได้ คลิก Apply เฉพาะเมื่อคุณต้องการเก็บการแก้ไขไว้ การเปิดองค์ประกอบเพียงอย่างเดียวไม่เปลี่ยนแปลง journey ที่กำลังทำงานอยู่

ฟิลด์ที่คุณปล่อยว่างไว้ใน Update หรือ End จะไม่ถูกส่ง สิ่งที่การ์ดแสดงในฟิลด์เหล่านั้นขึ้นอยู่กับแอปของคุณ: อาจเก็บค่าก่อนหน้าไว้ ล้างค่าทิ้ง หรือทำอย่างอื่น สอบถามทีมพัฒนาของคุณว่าแอปจัดการกรณีนี้อย่างไร

ใน End, Card content เป็นทางเลือก ฟิลด์ที่คุณกรอกจะกลายเป็นค่าสุดท้ายที่แสดงก่อนการ์ดปิด

ตั้งค่าลำดับความสำคัญและเวลาในการส่ง

Anchor link to

  1. ใน Delivery priority ให้เลือกว่า iOS ควรส่งการอัปเดตนี้เมื่อใด:

    • Immediate: iOS ส่งทันทีและสามารถปลุกโทรศัพท์ได้ (และเล่นเสียง หากคุณตั้งค่าไว้)
    • Quiet: iOS อาจส่งในภายหลังพร้อมกับการอัปเดตอื่นๆ และไม่ปลุกโทรศัพท์ทันที
    • Default (batched): iOS ใช้การส่งแบบกลุ่มเริ่มต้นของตัวเองและไม่ปลุกโทรศัพท์ทันที

  2. ใน Sound ให้เลือกเสียงจากรายการ ทีมพัฒนาของคุณเพิ่มไฟล์เสียงลงในบันเดิลแอป iOS ดู เสียง push แบบกำหนดเอง เสียงจะเล่นเฉพาะเมื่อมี Alert title หรือ Alert text เช่นเดียวกับแบนเนอร์

  3. ขึ้นอยู่กับ Action ที่คุณตั้งค่าสำหรับองค์ประกอบนี้ (Start, Update หรือ End) ให้กรอกหนึ่งในตัวเลือกต่อไปนี้:

    • Start หรือ Update: ตั้งค่า Stale after, min เป็นจำนวนนาทีที่ข้อมูลบนการ์ดควรดูเป็นข้อมูลใหม่ เมื่อเวลานั้นสิ้นสุดลง iOS จะทำให้ตัวเลขดูจางลงว่าล้าสมัย การ์ดยังคงอยู่บนหน้าจอล็อก เพื่อให้ตัวเลขยังคงดูเป็นข้อมูลปัจจุบัน ให้ส่ง Update อีกครั้งก่อนที่เวลาจะสิ้นสุด
    • End: ตั้งค่า Dismiss after, min เป็นระยะเวลาที่การ์ดที่ปิดแล้วยังคงอยู่บนหน้าจอล็อกก่อนที่ iOS จะลบออก ปล่อยไว้ที่ 0 และการ์ดจะยังคงแสดง Card content สุดท้ายจนกว่า iOS จะยกเลิกเองภายในเวลาไม่เกิน 4 ชั่วโมง

  4. คุณสามารถตั้งค่า Relevance score เป็นตัวเลขตั้งแต่ 1 ถึง 100 ได้ตามต้องการ เมื่อบุคคลหนึ่งมี Live Activity ที่ใช้งานอยู่มากกว่าหนึ่งรายการจากแอปของคุณพร้อมกัน iOS จะแสดงรายการที่มีคะแนนสูงกว่าก่อน ปล่อยไว้ที่ 0 เพื่อไม่ตั้งค่าความชอบ Pushwoosh จะไม่ส่งคะแนน 0 ไปยัง Apple เลย ดู กิจกรรมหลายรายการต่อหนึ่งอุปกรณ์ สำหรับภาพรวมทั้งหมด

ฟิลด์ Delivery priority, Sound, Stale after และ Relevance score บนองค์ประกอบ Start

กรอกการแจ้งเตือน Android

Anchor link to

กรอกหัวข้อ ข้อความ แถบความคืบหน้า และเวลาในส่วนหัวของการแจ้งเตือน Android ส่วนนี้จะปรากฏเฉพาะเมื่อเปิด Android Live Updates และใช้ Card language เดียวกับการ์ด iOS

  1. ตั้งค่า Notification title สำหรับทุกภาษาที่คุณกรอกสำหรับ Android ใน Start และ Update journey จะทำงานไม่ได้จนกว่าทุกภาษาเหล่านั้นจะมีหัวข้อ ภาษาที่ไม่มีหัวข้อจะแสดงข้อความเตือนในฟอร์ม

  2. ตั้งค่า Notification text

    หัวข้อส่วน Android Live Updates พร้อมข้อความคำแนะนำ และฟิลด์ Notification title และ text ที่กรอกแล้ว

  3. ตั้งค่าแถบความคืบหน้า:

    • Progress: พิมพ์ตัวเลขหรือ placeholder ในรูปแบบ {name} (หรือ {name|format} หรือ {name|format|default} ก็ได้) สำหรับตำแหน่งที่แถบควรอยู่ ในหน่วยเดียวกับความยาวของ segment
    • Segments: คลิก Add segment สำหรับแต่ละส่วนที่มีสีของแถบ และตั้งค่า Color แบบ hex (#RRGGBB หรือ #AARRGGBB) และ Length ให้แต่ละส่วน ความยาวของ segment ทั้งหมดรวมกันเป็นแถบเต็ม
    • Animate the bar without a known end: เปิดเพื่อแสดงแถบเคลื่อนไหวแทนค่า Progress
    • Hide the progress bar: เปิดเพื่อแสดงการ์ดโดยไม่มีแถบ

    Progress ตั้งเป็น 65, สวิตช์ Animate the bar และ Hide the progress bar ปิดอยู่ และกรอก Segments สองรายการแล้ว

  4. ตั้งค่าเวลาในส่วนหัว:

    • Header time: พิมพ์ Unix timestamp เป็นวินาที (ไม่ใช่มิลลิวินาที) หรือ placeholder สำหรับช่วงเวลาที่นาฬิกาในส่วนหัวของการ์ดควรแสดง ตัวอย่างเช่น 1735689600 หมายถึง 2025-01-01 00:00 UTC หากตั้งค่าทั้งฟิลด์นี้และ Header time after, min จะใช้ Header time
    • Header time after, min: ตั้งค่าจำนวนนาทีหลังการส่งที่เวลาในส่วนหัวควรแสดง
    • Run the header time as a timer: เปิดเพื่อแสดง Header time เป็นนาฬิกาที่เดินอยู่แทนค่าคงที่ ตัวเลือกนี้จะแสดง Count down to the header time
    • Count down to the header time: เปิดเพื่อนับถอยหลังไปยัง Header time แทนการนับขึ้นจากเวลาส่ง
    • Hide the header time: เปิดเพื่อแสดงการ์ดโดยไม่มีเวลาในส่วนหัว

    Header time ว่างเปล่า, Header time after ตั้งเป็น 8 นาที, Run the header time as a timer เปิดอยู่, Count down to the header time และ Hide the header time ปิดอยู่

ฟิลด์ใดๆ ข้างต้นสามารถมี placeholder ได้ ซึ่งจะถูกแทนค่าแบบเดียวกับฟิลด์ Card content ของ iOS: จากอีเวนต์ journey หรือปรับให้เป็นส่วนตัวด้วยแอตทริบิวต์ของอีเวนต์

การแตะที่การแจ้งเตือนจะเปิดแอป เช่นเดียวกับ push ปกติ

ตั้งค่าแบนเนอร์แจ้งเตือน

Anchor link to

ส่วนนี้ใช้เฉพาะเมื่อเปิด iOS Live Activity หากเปิดเฉพาะ Android Live Updates ฟิลด์เหล่านี้จะถูกซ่อนและไม่มีการส่งข้อมูลใดๆ

สำหรับทั้งสามการกระทำ (Start, Update และ End):

  1. ใน Alert title ให้ตั้งค่าหัวข้อแบนเนอร์ที่แสดงบนหน้าจอล็อก
  2. ใน Alert text ให้ตั้งค่าข้อความแบนเนอร์

ฟิลด์ Alert title และ Alert text กรอกแล้วสำหรับองค์ประกอบ Start

เลือกว่าอุปกรณ์ใดจะได้รับการ์ด

Anchor link to

การระบุที่อยู่จะถูกตั้งค่าเพียงครั้งเดียว ใน Start ปล่อยให้สวิตช์ทั้งสองปิดอยู่เพื่อส่งการ์ดไปยังอุปกรณ์ที่ผู้เดินทางเข้าสู่ journey การเปิดสวิตช์หนึ่งจะปิดอีกสวิตช์หนึ่ง:

  • Send to all devices of this user: ส่งไปยังทุกอุปกรณ์ที่ลงทะเบียนภายใต้ User ID ของผู้เดินทางคนนั้น ไม่ใช่แค่อุปกรณ์ที่พวกเขาใช้เข้าสู่ journey
  • Send to the last active device only: ส่งไปยังอุปกรณ์เดียวที่ User ID นั้นใช้ล่าสุด แทนที่จะส่งไปยังทุกอุปกรณ์หรืออุปกรณ์ที่เข้า

ใน Update และ End ให้ตรวจสอบ Delivery (from the start element) ซึ่งระบุชื่อโหมดการระบุที่อยู่จาก Start ที่เชื่อมโยง การอัปเดตสามารถเข้าถึงได้เฉพาะการ์ดเดียวกันเท่านั้น ดังนั้นจึงออกไปในลักษณะเดียวกัน

ปรับให้เนื้อหาเป็นส่วนตัว

Anchor link to

ใช้สิ่งนี้เมื่อ placeholder ใน Alert title, Alert text, Card content หรือ Notification title, Notification text, Progress หรือ Header time ของ Android ควรรับค่าจากอีเวนต์ journey หรือการเข้าที่ใช้ API แทนที่จะเป็นแท็กอุปกรณ์

  1. ภายใต้ Overwrite personalization ให้เปิด Personalise message with event attributes
  2. ทำเครื่องหมายที่ช่อง Overwrite placeholder ข้าง placeholder แต่ละรายการที่คุณต้องการแมปใหม่
  3. แมป placeholder นั้นกับแอตทริบิวต์ของอีเวนต์

บล็อก Overwrite personalization พร้อมเปิดใช้งานสวิตช์ Personalise message with event attributes

บันทึกองค์ประกอบ

Anchor link to

คลิก Apply เพื่อบันทึกการตั้งค่าองค์ประกอบ Apply จะบันทึกองค์ประกอบนี้ไว้ใน journey แต่ไม่ได้ยืนยันว่าการ์ดปรากฏบนอุปกรณ์แล้ว หลังจาก journey เริ่มทำงาน ให้ตรวจสอบ Total entries และการหลุดออกในขั้นตอนนี้ และตรวจสอบการ์ดบน iPhone ที่ใช้ทดสอบ อุปกรณ์ Android 16 ขึ้นไปที่ใช้ทดสอบ หรือทั้งสองอย่าง ขึ้นอยู่กับแพลตฟอร์มที่คุณเปิดไว้

ข้อจำกัด

Anchor link to
  • สถิติองค์ประกอบ: ในขั้นตอนนี้ ให้ตรวจสอบ Total entries แถว Delivery (โหมดการระบุที่อยู่) และการหลุดออก (No recipient for the card, Live Activity send failed) ใช้ No recipient for the card เพื่อดูว่าการส่งข้อความไม่พบอุปกรณ์สำหรับแพลตฟอร์มที่เปิดไว้ในโหมดนั้น ไม่ใช่ว่าอุปกรณ์ไม่มีโทเค็น Live Activity ขั้นตอนนี้ไม่รายงานว่าอุปกรณ์แสดงการ์ดหรือผู้ใช้เปิดการ์ดหรือไม่
  • เสียงไม่รับประกันในทุกการอัปเดต: iOS จำกัดอัตราการแจ้งเตือน Live Activity ด้วยตัวเอง การอัปเดตที่เหมือนกันอาจเล่นเสียงครั้งหนึ่งและมาถึงแบบเงียบในครั้งถัดไป
  • การกระทำ Start จำนวนมากติดต่อกันระหว่างการทดสอบ: หากคุณส่งการกระทำ Start ประมาณสิบครั้งสำหรับบุคคลเดียวกันในเวลาอันสั้น (เช่น ขณะทดสอบ journey) Apple อาจหยุดแสดงการ์ดใหม่และไม่ส่งคืนข้อผิดพลาด ใน journey บุคคลนั้นอาจยังคงดูเหมือนได้รับการส่งแล้ว ให้เว้นช่วงระหว่างการรันทดสอบ