วิธีรองรับการส่ง Push โดยตรงด้วย Token ของ FCM/APNs

สถานการณ์ที่ใช้ได้

บทความนี้เหมาะกับคุณ หากแอปของคุณอยู่ในสถานการณ์ต่อไปนี้:

• แอปเชื่อมต่อกับ Google FCM และ iOS APNs โดยตรงอยู่แล้ว ถือครอง FCM Token และ APNs Token ด้วยตนเอง และส่ง Push ด้วยโปรโตคอลแบบเนทีฟ
• แอปเวอร์ชันเก่าไม่ได้ผสานรวม EngageLab AppPush SDK ทำให้ผู้ใช้เดิมจำนวนมากไม่มี registration_id ของ EngageLab และไม่สามารถเข้าถึงได้ผ่าน API สร้าง Push
• คุณต้องการนำผู้ใช้เดิมเหล่านี้เข้าสู่ระบบ Push ของ EngageLab ก่อนโดยไม่บังคับให้อัปเดตแอป แล้วจึงค่อยย้ายไปใช้ SDK ทีละขั้น

ภาพรวมของแนวทาง

EngageLab มี API ลงทะเบียนอุปกรณ์ สำหรับสถานการณ์นี้: ฝั่งเซิร์ฟเวอร์ของคุณส่ง FCM Token หรือ APNs Device Token ที่ถือครองอยู่เข้ามาโดยตรง แล้ว EngageLab จะสร้าง registration_id ที่ผูกกับ Token นั้นอย่างเฉพาะเจาะจง จากนั้นคุณสามารถส่งข้อความตาม registration_id ผ่าน API สร้าง Push ได้เช่นเดียวกับผู้ใช้ที่ลงทะเบียนผ่าน SDK และใช้ความสามารถที่อิงกับ registration_id เช่น แท็ก นามแฝง และสถิติได้

flowchart LR
    token["FCM / APNs Token<br/>ที่คุณถือครองอยู่"]
    register["API ลงทะเบียนอุปกรณ์<br/>/v4/devices/token/registration_id"]
    regId["registration_id"]
    push["API สร้าง Push<br/>/v4/push"]
    device["อุปกรณ์ของผู้ใช้<br/>ได้รับการแจ้งเตือน"]

    token --> register --> regId --> push --> device

ขั้นตอนการเชื่อมต่อ:

1. ฝั่งเซิร์ฟเวอร์เรียก API ลงทะเบียนอุปกรณ์เพื่อส่ง Token เป็นชุดตามแพลตฟอร์ม (ครั้งละ 1–500 รายการ) และบันทึกการจับคู่ระหว่าง registration_id ที่ได้รับกับ Token แต่ละรายการ
2. เมื่อส่ง Push ให้ระบุ registration_id ของผู้ใช้ปลายทางใน to.registration_id ของ API สร้าง Push
3. เมื่อ Token เปลี่ยน (FCM onNewToken หรือ APNs ลงทะเบียนใหม่) ให้เรียก API ลงทะเบียนอุปกรณ์อีกครั้งเพื่อรับ registration_id ใหม่

คำถามที่พบบ่อยหลังเชื่อมต่อคือ: เมื่อผู้ใช้แตะการแจ้งเตือนบนโทรศัพท์ แอปจะเปิดหน้าแรก หรือสามารถเข้าสู่หน้าปลายทางเช่นรายละเอียดคำสั่งซื้อได้โดยตรง? เนื้อหาต่อไปนี้จะอธิบายโดยใช้ FCM บน Android เป็นตัวอย่าง

การนำทางเมื่อแตะการแจ้งเตือน: สรุป

สามารถนำทางไปยังหน้าปลายทางได้ แต่ไม่ได้มีให้อัตโนมัติเพียงเพราะลงทะเบียน registration_id แล้ว

• โดยค่าเริ่มต้น การแตะการแจ้งเตือนจะเพียงเปิดแอปเท่านั้น
• จะเข้าสู่หน้าใดนั้นขึ้นอยู่กับตรรกะการจัดการการแตะของแอปของคุณเอง
• หากต้องการนำทางไปยังหน้าปลายทาง ฝั่งเซิร์ฟเวอร์ต้องระบุ intent.url ในคำขอส่ง Push และแอปของคุณต้องมี Activity ที่สามารถตอบสนองต่อ action นั้นได้

API ลงทะเบียนอุปกรณ์ทำหน้าที่เพียงสร้างการจับคู่ระหว่าง FCM Token กับ registration_id เท่านั้น ไม่ได้เพิ่มความสามารถในการนำทางหน้าใดๆ ให้กับแอปของคุณ และผู้ใช้กลุ่มนี้จะไม่ผ่านตรรกะกลางสำหรับการแตะการแจ้งเตือนที่ต้องอาศัย EngageLab SDK ดังนั้นนี่จึงเป็นแนวทางในช่วงเปลี่ยนผ่าน และในระยะยาวยังคงแนะนำให้ย้ายไปใช้ EngageLab AppPush SDK ดูรายละเอียดในหัวข้อ "คำแนะนำระยะยาว" ท้ายบทความ

พฤติกรรมเริ่มต้น: ไม่ตั้งค่าการทำงานเมื่อแตะ

เมื่อคำขอส่ง Push ไม่ได้ตั้งค่า notification.android.intent การแจ้งเตือนที่ EngageLab ส่งให้ FCM จะไม่มี click_action พฤติกรรมเมื่อแตะในกรณีนี้จะเป็นไปตามพฤติกรรมเริ่มต้นของ FCM ทั้งหมด:

• เมื่อแอปอยู่ในพื้นหลังหรือถูกปิดไปแล้ว FCM จะแสดงการแจ้งเตือนโดยอัตโนมัติ และเมื่อแตะจะเปิด Activity เริ่มต้นของแอป (Activity ที่ประกาศเป็น MAIN/LAUNCHER ใน AndroidManifest.xml)
• ผู้ใช้ปลายทางจะเห็นหน้าแรก หน้าเข้าสู่ระบบ หรือกลับไปยังหน้าที่เคยเปิดค้างไว้ ขึ้นอยู่กับตรรกะการเริ่มต้นของแอปของคุณและสถานะ task stack ในขณะนั้น

ดังนั้น "เปิดแอปโดยค่าเริ่มต้น" จึงไม่เท่ากับ "กลับไปหน้าแรกเสมอ" ดูรายละเอียดในเอกสารทางการของ Firebase: รับข้อความในแอป Android

การนำทางไปยังหน้าปลายทาง: intent.url → click_action

เส้นทางการแมป

เซิร์ฟเวอร์ EngageLab จะแมปค่าของ notification.android.intent.url ใน API สร้าง Push ไปยังฟิลด์ android.notification.click_action ของการแจ้งเตือน FCM จากนั้นระบบ Android จะค้นหา Activity ในแอปของคุณที่ตรงกับ action นั้น

flowchart LR
    pushApi["API สร้าง Push<br/>notification.android.intent.url"]
    fcm["ข้อความ FCM<br/>android.notification.click_action"]
    activity["แอปของคุณ<br/>Activity ที่ตรงกับ action"]
    target["หน้าธุรกิจปลายทาง<br/>(เช่น รายละเอียดคำสั่งซื้อ)"]

    pushApi --> fcm --> activity --> target

คำจำกัดความทางการของ click_action ดูได้ที่ FCM AndroidNotification

ขั้นตอนที่ 1: ฝั่งเซิร์ฟเวอร์ระบุ intent.url ในคำขอส่ง Push

เมื่อส่ง Push ตาม registration_id ให้เพิ่ม intent.url ใน notification.android และส่งพารามิเตอร์ทางธุรกิจผ่าน extras:

              
              curl -X POST https://pushapi-sgp.engagelab.com/v4/push \
  -u "appKey:masterSecret" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "push",
    "to": {
      "registration_id": ["13065ffa4e1a6cc91c3"]
    },
    "body": {
      "platform": "android",
      "notification": {
        "android": {
          "title": "จัดส่งคำสั่งซื้อแล้ว",
          "alert": "คำสั่งซื้อ 20260911001 ของคุณจัดส่งแล้ว แตะเพื่อดูสถานะการขนส่ง",
          "intent": {
            "url": "intent:#Intent;action=com.example.app.ORDER_DETAIL;component=com.example.app/com.example.app.OrderDetailActivity;end"
          },
          "extras": {
            "order_id": "20260911001",
            "page": "order_detail"
          }
        }
      }
    },
    "request_id": "order-shipped-20260911001"
  }'

            

ข้อควรทราบเกี่ยวกับค่าของ intent.url:

• เป็นรูปแบบ Intent URI ของ Android (intent:#Intent;...;end) ไม่ใช่ที่อยู่เว็บเพจที่กรอกได้ตามใจ
• action คือชื่อการทำงานที่แอปของคุณกำหนดเอง ส่วน component คือ ชื่อแพ็กเกจ/ชื่อคลาสเต็มของ Activity
• ใน url เดียวกัน สามารถระบุเพียง action หรือ component อย่างใดอย่างหนึ่งได้ แต่แนะนำให้ระบุทั้งสองค่าเพื่อให้ตรงกับ Activity ปลายทางอย่างแม่นยำ
• ประเภทค่าอื่นๆ (เปิดหน้าแรก, Deeplink ฯลฯ) ดูคำอธิบาย intent ใน ฟิลด์การแจ้งเตือน android ของ API สร้าง Push

ขั้นตอนที่ 2: แอปของคุณจัดเตรียม Activity ที่ตรงกัน

ใน AndroidManifest.xml ให้ประกาศ intent-filter ให้กับ Activity ปลายทาง โดยใช้ action ที่ตรงกับใน intent.url:

              
              <activity
    android:name=".OrderDetailActivity"
    android:exported="true">
    <intent-filter>
        <action android:name="com.example.app.ORDER_DETAIL" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

            

หลังจาก FCM แสดงการแจ้งเตือนและผู้ใช้แตะ ระบบจะเปิด Activity ที่เกี่ยวข้องด้วย action นั้น และนำคู่คีย์-ค่าใน extras ของการแจ้งเตือนใส่ลงใน extras ของ Intent Activity ปลายทางจะอ่านพารามิเตอร์และดำเนินการกำหนดเส้นทางทางธุรกิจ:

              
              class OrderDetailActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        val orderId = intent.getStringExtra("order_id")
        if (orderId.isNullOrEmpty()) {
            // หากไม่มีพารามิเตอร์ ให้กลับไปยังรายการคำสั่งซื้อหรือหน้าแรก
            startActivity(Intent(this, MainActivity::class.java))
            finish()
            return
        }
        showOrderDetail(orderId)
    }
}

            

หากแอปของคุณมีหน้ากลางสำหรับกำหนดเส้นทางแบบรวมศูนย์อยู่แล้ว (เช่น การแตะการแจ้งเตือนทั้งหมดจะเข้าสู่ PushRouterActivity ก่อน แล้วจึงกระจายไปยังหน้าต่างๆ ตามพารามิเตอร์) คุณสามารถชี้ component ใน intent.url ไปยังหน้ากลางนั้น ให้หน้ากลางอ่าน extras แล้วนำทางไปยังหน้าธุรกิจ เช่น รายละเอียดคำสั่งซื้อ โดยไม่ต้องประกาศ action แยกสำหรับแต่ละหน้าธุรกิจ

ข้อควรระวัง

• จำเป็นต้องผสานรวม EngageLab SDK หรือไม่: ไม่จำเป็น เส้นทางข้างต้นอาศัยเพียงกลไก click_action ของ FCM และการประกาศ Activity ในแอปของคุณเองเท่านั้น
• การจัดการ click_action ที่มีอยู่แล้วนำมาใช้ซ้ำได้: หากแอปของคุณเคยส่ง Push ผ่าน FCM โดยตรงและมีตรรกะจัดการ click_action อยู่แล้ว เพียงนำค่า action เดิมมาใส่ใน intent.url ก็ใช้ซ้ำได้
• หากยังไม่มีการจัดการ click_action ต้องเพิ่มเติม: หากปัจจุบันแอปของคุณอาศัยเพียงพฤติกรรมเปิดแอปแบบเริ่มต้น จำเป็นต้องเพิ่มการประกาศ Activity และตรรกะแยกวิเคราะห์พารามิเตอร์ตาม "ขั้นตอนที่ 2" ไม่เช่นนั้นแม้ฝั่งเซิร์ฟเวอร์จะตั้งค่า intent.url แล้ว ระบบก็จะหา Activity ที่ตอบสนองได้ไม่พบ
• ส่งพารามิเตอร์ทางธุรกิจผ่าน extras: intent.url ใช้กำหนดว่า "จะเปิดหน้าใด" ส่วนเนื้อหาที่แสดงในหน้านั้นแนะนำให้ส่งผ่าน extras (เช่น order_id) และให้ Activity ปลายทางแยกวิเคราะห์เอง
• พฤติกรรมเมื่อแอปอยู่เบื้องหน้า: เมื่อแอปอยู่เบื้องหน้า FCM จะไม่แสดงการแจ้งเตือนอัตโนมัติ แต่จะเรียกกลับไปที่ onMessageReceived ของแอปของคุณ การจะแสดงการแจ้งเตือนหรือไม่และจะนำทางอย่างไรเมื่อแตะ แอปของคุณต้องเป็นผู้ดำเนินการเองทั้งหมด
• วิธีตรวจสอบ: ขณะทดสอบร่วมกัน ให้ใช้ intent:#Intent;action=android.intent.action.MAIN;end ก่อนเพื่อยืนยันว่าเส้นทางของช่องทางทำงานปกติ แล้วจึงเปลี่ยนเป็น action ทางธุรกิจเพื่อตรวจสอบการนำทางไปยังหน้าปลายทาง

คำแนะนำระยะยาว: ย้ายไปใช้ EngageLab AppPush SDK โดยเร็วที่สุด

API ลงทะเบียนอุปกรณ์ถูกวางตำแหน่งเป็นแนวทางรองรับความเข้ากันได้ในช่วงเปลี่ยนผ่าน เพื่อให้ผู้ใช้เดิมของแอปเวอร์ชันเก่าสามารถเข้าถึงได้แม้ยังไม่ได้ผสานรวม SDK และสร้าง registration_id ที่เกี่ยวข้องไว้ เพื่อเตรียมพร้อมสำหรับการใช้ความสามารถอื่นๆ ของ EngageLab AppPush ในภายหลัง สิ่งที่ API นี้แก้ไขคือปัญหา "ส่งถึงได้หรือไม่" ไม่ใช่การมาแทนที่ SDK

เราแนะนำให้คุณมองว่านี่เป็นส่วนหนึ่งของกลยุทธ์การย้ายระบบ ไม่ใช่แนวทางระยะยาว:

• แอปเวอร์ชันใหม่ผสานรวม EngageLab AppPush SDK: ผู้ใช้ใหม่จะได้รับ registration_id ผ่านการลงทะเบียนมาตรฐานของ SDK และได้รับความสามารถในการแสดงการแจ้งเตือนและจัดการการแตะอย่างครบถ้วนทันที
• แอปเวอร์ชันเก่าใช้ Token โดยตรงในช่วงเปลี่ยนผ่าน: ผู้ใช้เดิมยังคงรับ Push ผ่าน registration_id ที่ลงทะเบียนด้วย API ลงทะเบียนอุปกรณ์ต่อไป ทั้งสองระบบสามารถอยู่ร่วมกันได้โดยไม่จำเป็นต้องบังคับรวมกัน
• ค่อยๆ รวมศูนย์ตามการอัปเดตเวอร์ชัน: เมื่อผู้ใช้อัปเกรดไปยังเวอร์ชันที่ผสานรวม SDK ผู้ใช้แบบ Token โดยตรงจะลดลงเองตามธรรมชาติ และในที่สุดจะรวมเป็นระบบ SDK เดียว

เมื่อเทียบกับวิธีเชื่อมต่อโดยตรงที่แนะนำในบทความนี้ หลังผสานรวม SDK แล้ว:

• การนำทางเมื่อแตะการแจ้งเตือนจะถูกจัดการโดย SDK อย่างเป็นเอกภาพ ทั้งสามประเภทที่ intent.url รองรับ (Activity ที่ระบุ, หน้าแรกของแอป, Deeplink) ไม่ต้องให้คุณประกาศ action และตรรกะแยกวิเคราะห์ทีละรายการในฝั่งแอป
• การแสดงการแจ้งเตือนขณะอยู่เบื้องหน้า สไตล์แถบการแจ้งเตือน (builder_id, style, channel_id ฯลฯ) ป้ายตัวเลข การยุบข้อความ และฟิลด์อื่นๆ จะทำงานได้อย่างสมบูรณ์
• SDK จะรายงานข้อมูลอุปกรณ์และพฤติกรรมเช่นการแตะโดยอัตโนมัติ ทำให้สถิติการส่งถึงและการแตะในคอนโซลครบถ้วนยิ่งขึ้น

วิธีการผสานรวมโปรดดู คู่มือการผสานรวม Android SDK และ คู่มือการผสานรวม iOS SDK