Live Updates บน Android

Pushwoosh รองรับ Android Live Updates ผ่านโมดูล pushwoosh-liveupdates (SDK 6.9.0 และใหม่กว่า) Live Update คือการแจ้งเตือนแบบแสดงความคืบหน้าอย่างต่อเนื่องที่ระบบจะโปรโมตบนหน้าจอล็อก, ในลิ้นชักการแจ้งเตือน, และเป็นชิปสถานะในแถบสถานะ เพื่อให้ผู้ใช้สามารถติดตามกิจกรรมได้โดยไม่ต้องเปิดแอปของคุณ

lifecycle ทั้งหมดถูกขับเคลื่อนจากเซิร์ฟเวอร์: backend ของคุณจะส่ง push เมื่อกิจกรรมเริ่มต้น, ส่ง push เพิ่มเติมเมื่อมีความคืบหน้า, และส่ง push สุดท้ายเมื่อกิจกรรมสิ้นสุด SDK จะแสดงผลแต่ละรายการโดยอัตโนมัติ

Live Updates คืออะไร

Live Updates ถูกนำมาใช้ใน Android 16 (API 36) เพื่อเป็นวิธีการแสดงกิจกรรมที่ผู้ใช้เริ่มต้นและมีความสำคัญต่อเวลาตั้งแต่ต้นจนจบ โดยสร้างขึ้นบนการแจ้งเตือนที่เน้นความคืบหน้าของแพลตฟอร์มและ Notification.ProgressStyle API โดยแนวคิดแล้ว นี่คือฟีเจอร์ของ Android ที่เทียบเท่ากับ Live Activities ของ iOS

หน้านี้ครอบคลุมเฉพาะการผสานรวมกับ Pushwoosh เท่านั้น สำหรับพฤติกรรมของแพลตฟอร์ม, กฎการโปรโมต, และคำแนะนำด้านการออกแบบ โปรดดูเอกสารอย่างเป็นทางการของ Android:

เมื่อใดควรใช้ Live Updates

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

การจัดส่งอาหาร — รับออเดอร์แล้ว, กำลังเตรียม, กำลังจัดส่ง, กำลังจะถึง
การเรียกรถและแท็กซี่ — กำหนดคนขับแล้ว, กำลังเดินทาง, กำลังจะถึง, การเดินทางกำลังดำเนินอยู่
การติดตามคำสั่งซื้อและการจัดส่ง — สถานะสดของคำสั่งซื้อที่กำลังอยู่ในระหว่างการขนส่ง
กีฬาสดและสื่อ — คะแนนการแข่งขันและเวลาขณะที่เกมดำเนินไป
ฟิตเนส — การออกกำลังกายหรือการวิ่งที่กำลังดำเนินอยู่พร้อมเวลาที่ผ่านไปและความคืบหน้า
ฟินเทค — ธุรกรรมหรือขั้นตอนการยืนยันที่กำลังเคลื่อนผ่านขั้นตอนต่างๆ

เนื่องจาก lifecycle ถูกขับเคลื่อนโดยเหตุการณ์จริงที่ backend ของคุณทราบอยู่แล้ว (สถานะคำสั่งซื้อเปลี่ยนแปลง, พนักงานจัดส่งกำลังเคลื่อนที่) โดยปกติแล้ว Live Update จะเป็นการเรียก API call เพียงครั้งเดียวที่เชื่อมต่อกับ event flow ที่มีอยู่ของคุณ — ไม่ใช่สิ่งที่คนส่งด้วยตนเอง

ข้อกำหนด

Android 16 (API 36) หรือใหม่กว่า บนอุปกรณ์รุ่นเก่า โมดูลจะยังคงไม่ทำงานและการเรียก Live Update API ทุกครั้งจะเป็น no-op ที่ปลอดภัย
Pushwoosh Android SDK 6.9.0 หรือใหม่กว่า

เพิ่มโมดูล pushwoosh-liveupdates

เพิ่ม dependency ไปยัง app/build.gradle ของคุณ:

dependencies {
    implementation 'com.pushwoosh:pushwoosh-liveupdates:<latest-version>'
}

แทนที่ <latest-version> ด้วยเวอร์ชันปัจจุบันจาก Maven Central

โมดูลจะถูกค้นพบโดยอัตโนมัติเมื่อเริ่มต้น มันจะประกาศ permission POST_PROMOTED_NOTIFICATIONS ที่จำเป็น, ลงทะเบียน notification channel ของตัวเอง, และสกัดกั้น Live Update pushes ก่อนที่จะไปถึงเส้นทางการแจ้งเตือนเริ่มต้น ไม่จำเป็นต้องมีโค้ดเริ่มต้นเพิ่มเติม — SDK จะตั้งค่า ongoing และ promoted flags, ดาวน์โหลด large icon, แมปปุ่ม action, และโพสต์การแจ้งเตือนให้คุณ

ส่ง Live Update

คุณส่ง Live Updates ผ่าน Messaging API v2 โดยการเพิ่มฟิลด์ Live Update ไปยังอ็อบเจกต์ root_params ของ android content block ใช้คำขอแบบ transactional — Live Update จะกำหนดเป้าหมายไปยังผู้ใช้เฉพาะรายที่กำลังติดตามกิจกรรมนั้นๆ ฟิลด์ schedule เป็นสิ่งจำเป็น; { "after": "0s" } จะส่งทันที lifecycle มีสามการดำเนินการ ตั้งค่าใน pw_live_op:

start — push แรกสำหรับกิจกรรม โพสต์การแจ้งเตือนที่กำลังดำเนินอยู่
update — push ต่อมาสำหรับกิจกรรมเดียวกัน รีเฟรชในตำแหน่งเดิมอย่างเงียบๆ
end — push สุดท้าย ปิดการแจ้งเตือน

push ทั้งหมดที่อยู่ในกิจกรรมเดียวกันต้องใช้ pw_live_id เดียวกัน id นั้นจะผูกการอัปเดตเข้าด้วยกันและยังเป็นสิ่งที่คุณใช้เพื่อปิดการอัปเดตจากแอป

แต่ละ push จะอธิบายการแจ้งเตือนอย่างสมบูรณ์ — ไม่มีอะไรถูกส่งต่อมาจาก push ก่อนหน้า ส่งทุกฟิลด์ที่คุณต้องการเก็บไว้ซ้ำ เช่น segments และ large icon ในแต่ละ update; ฟิลด์ที่ละไว้จะถูกแสดงผลว่าไม่มีอยู่

พารามิเตอร์ Live Update

คีย์เหล่านี้จะอยู่ภายในอ็อบเจกต์ root_params ของ android content block Title, body, และ large icon ใช้ฟิลด์ push มาตรฐานของ Android (title, body, custom_icon)

พารามิเตอร์	ประเภท	คำอธิบาย
`pw_live_op`	string	การดำเนินการของ Lifecycle: `start`, `update`, หรือ `end` จำเป็น
`pw_live_id`	string	id กิจกรรมที่คงที่ซึ่งใช้ร่วมกันโดย push ทั้งหมดของ Live Update หนึ่งรายการ จำเป็น
`pw_live_progress`	int	ค่าความคืบหน้า วัดจากความยาวรวมของ segment
`pw_live_progress_indeterminate`	bool	แสดงแอนิเมชั่นที่ไม่แน่นอนแทนค่าที่ระบุ
`pw_live_segments`	JSON string	segment ความคืบหน้าที่เรียงลำดับ แต่ละรายการคือ `{"color": "#RRGGBB", "length": N}`
`pw_live_extras`	JSON string	ข้อมูลใดๆ ที่ส่งผ่านไปยัง style provider แบบกำหนดเอง
`pw_live_when`	long	จุดยึดเวลาของส่วนหัว ในหน่วยมิลลิวินาทีของ epoch
`pw_live_chronometer`	bool	แสดงเวลาของส่วนหัวเป็นตัวจับเวลาที่กำลังทำงาน
`pw_live_chronometer_count_down`	bool	ตัวจับเวลาที่กำลังทำงานจะนับถอยหลังแทนที่จะนับขึ้น
`pw_live_show_when`	bool	แสดงคอลัมน์เวลาของส่วนหัวเลยหรือไม่ ค่าเริ่มต้นคือ `true`

ฟิลด์เวลาทั้งสี่ทำงานร่วมกันดังนี้: เมื่อ pw_live_show_when ถูกตั้งค่าเป็น false เวลาจะถูกซ่อน; มิฉะนั้น pw_live_when จะเป็นจุดยึด, pw_live_chronometer จะเปลี่ยนเป็นตัวนับสด, และ pw_live_chronometer_count_down จะทำให้ตัวนับนั้นทำงานถอยหลัง

Push เริ่มต้น

curl -X POST https://api.pushwoosh.com/messaging/v2/notify \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transactional": {
      "application": "XXXXX-XXXXX",
      "platforms": ["ANDROID"],
      "users": { "list": ["customer-42"] },
      "payload": {
        "content": {
          "localized_content": {
            "default": {
              "android": {
                "title": "Order #4521",
                "body": "We are preparing your order",
                "custom_icon": "https://example.com/restaurant.png",
                "root_params": {
                  "pw_live_op": "start",
                  "pw_live_id": "order_4521",
                  "pw_live_progress": "1",
                  "pw_live_segments": "[{\"color\":\"#34A853\",\"length\":3},{\"color\":\"#FBBC05\",\"length\":4},{\"color\":\"#4285F4\",\"length\":3}]",
                  "pw_live_extras": "{\"eta\":\"18:40\"}"
                }
              }
            }
          }
        }
      },
      "schedule": { "after": "0s" },
      "message_type": "MESSAGE_TYPE_TRANSACTIONAL"
    }
  }'

Push อัปเดต

ส่ง update ด้วย pw_live_id เดียวกันทุกครั้งที่กิจกรรมมีความคืบหน้า ส่ง segments และไอคอนซ้ำ — การอัปเดตที่ละเว้นสิ่งเหล่านี้จะแสดงผลโดยไม่มีสิ่งเหล่านั้น

curl -X POST https://api.pushwoosh.com/messaging/v2/notify \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transactional": {
      "application": "XXXXX-XXXXX",
      "platforms": ["ANDROID"],
      "users": { "list": ["customer-42"] },
      "payload": {
        "content": {
          "localized_content": {
            "default": {
              "android": {
                "title": "Order #4521",
                "body": "Your courier is on the way",
                "custom_icon": "https://example.com/restaurant.png",
                "root_params": {
                  "pw_live_op": "update",
                  "pw_live_id": "order_4521",
                  "pw_live_progress": "7",
                  "pw_live_segments": "[{\"color\":\"#34A853\",\"length\":3},{\"color\":\"#FBBC05\",\"length\":4},{\"color\":\"#4285F4\",\"length\":3}]"
                }
              }
            }
          }
        }
      },
      "schedule": { "after": "0s" },
      "message_type": "MESSAGE_TYPE_TRANSACTIONAL"
    }
  }'

Push สิ้นสุด

push สุดท้ายต้องการเพียงการดำเนินการและ id เท่านั้น

curl -X POST https://api.pushwoosh.com/messaging/v2/notify \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transactional": {
      "application": "XXXXX-XXXXX",
      "platforms": ["ANDROID"],
      "users": { "list": ["customer-42"] },
      "payload": {
        "content": {
          "localized_content": {
            "default": {
              "android": {
                "root_params": {
                  "pw_live_op": "end",
                  "pw_live_id": "order_4521"
                }
              }
            }
          }
        }
      },
      "schedule": { "after": "0s" },
      "message_type": "MESSAGE_TYPE_TRANSACTIONAL"
    }
  }'

ปรับแต่งรูปลักษณ์

SDK มาพร้อมกับ progress style เริ่มต้นที่สร้างจาก pw_live_progress, pw_live_progress_indeterminate, และ pw_live_segments หากต้องการควบคุม progress bar อย่างเต็มที่ ให้ implement LiveUpdateProgressStyleProvider และสร้าง Notification.ProgressStyle ด้วยตัวคุณเอง

provider เป็นจุดปรับแต่งเพียงจุดเดียว SDK ยังคงเป็นเจ้าของการตั้งค่า channel, ongoing และ promoted flags, large icon, action buttons, และ header time — provider แบบกำหนดเองสามารถปรับแต่งได้เฉพาะ progress bar เท่านั้น ดังนั้นจึงไม่สามารถทำลายคุณสมบัติการโปรโมตได้ มันต้องเป็น stateless: สร้าง style ที่ส่งคืนจาก LiveUpdateState ที่ให้มาเท่านั้น หากเกิดข้อผิดพลาด SDK จะกลับไปใช้ style เริ่มต้นและการแจ้งเตือนจะยังคงถูกโพสต์

Java
Kotlin

import android.app.Notification;
import androidx.annotation.NonNull;
import com.pushwoosh.liveupdates.LiveUpdateProgressStyleProvider;
import com.pushwoosh.liveupdates.LiveUpdateSegment;
import com.pushwoosh.liveupdates.LiveUpdateState;
import java.util.List;

public class OrderStyleProvider implements LiveUpdateProgressStyleProvider {
    @NonNull
    @Override
    public Notification.ProgressStyle createStyle(@NonNull LiveUpdateState state) {
        Notification.ProgressStyle style = new Notification.ProgressStyle();
        if (state.getProgress() != null) {
            style.setProgress(state.getProgress());
        }
        style.setProgressIndeterminate(state.isProgressIndeterminate());

        List<LiveUpdateSegment> segments = state.getSegments();
        int boundary = 0;
        for (int i = 0; i < segments.size(); i++) {
            LiveUpdateSegment seg = segments.get(i);
            style.addProgressSegment(
                new Notification.ProgressStyle.Segment(seg.getLength()).setColor(seg.getColor()));
            boundary += seg.getLength();
            if (i < segments.size() - 1) {
                style.addProgressPoint(new Notification.ProgressStyle.Point(boundary));
            }
        }
        return style;
    }
}

import android.app.Notification
import com.pushwoosh.liveupdates.LiveUpdateProgressStyleProvider
import com.pushwoosh.liveupdates.LiveUpdateState

class OrderStyleProvider : LiveUpdateProgressStyleProvider {
    override fun createStyle(state: LiveUpdateState): Notification.ProgressStyle {
        val style = Notification.ProgressStyle()
        state.progress?.let { style.setProgress(it) }
        style.setProgressIndeterminate(state.isProgressIndeterminate)

        val segments = state.segments
        var boundary = 0
        segments.forEachIndexed { i, seg ->
            style.addProgressSegment(
                Notification.ProgressStyle.Segment(seg.length).setColor(seg.color))
            boundary += seg.length
            if (i < segments.size - 1) {
                style.addProgressPoint(Notification.ProgressStyle.Point(boundary))
            }
        }
        return style
    }
}

ลงทะเบียน provider ด้วยแท็ก <meta-data> ใน AndroidManifest.xml คลาสต้องมี public constructor ที่ไม่มีอาร์กิวเมนต์

<meta-data
    android:name="com.pushwoosh.LIVE_UPDATE_STYLE_PROVIDER"
    android:value="com.example.OrderStyleProvider" />

ใช้ LiveUpdateState.getExtras() เพื่ออ่าน JSON ที่คุณส่งใน pw_live_extras และปรับ style ให้เข้ากับข้อมูลธุรกิจของคุณเอง

จัดการ Live Updates จากแอปของคุณ

เซิร์ฟเวอร์ขับเคลื่อนทุก start, update, และ end ดังนั้นจึงไม่มี API ฝั่งแอปเพื่อโพสต์หรือรีเฟรช Live Update facade PushwooshLiveUpdates ครอบคลุมเฉพาะสิ่งที่เซิร์ฟเวอร์ไม่สามารถทำได้ — การปิดการอัปเดตในเครื่องและการตรวจสอบว่ามีรายการใดแสดงอยู่บนหน้าจอ

import com.pushwoosh.liveupdates.PushwooshLiveUpdates;

// ปิด Live Update ที่ระบุเมื่อผู้ใช้เสร็จสิ้นกิจกรรมในแอป
// โดยไม่ต้องรอ push "end" สุดท้ายจากเซิร์ฟเวอร์
PushwooshLiveUpdates.endLiveUpdate("order_4521");

// แสดงรายการ id กิจกรรมที่แอปนี้กำลังแสดงอยู่
List<String> active = PushwooshLiveUpdates.getActiveIds();

// ล้างทุกอย่างที่แอปนี้กำลังแสดงอยู่ เช่น เมื่อออกจากระบบ
PushwooshLiveUpdates.endAllLiveUpdates();

เมธอดทั้งหมดปลอดภัยที่จะเรียกจากเธรดใดก็ได้และเป็น no-op บนอุปกรณ์ที่ต่ำกว่า Android 16