Bagikan melalui

Pendaftaran perangkat pemberitahuan push untuk pengembang aplikasi

  • Artikel

Untuk mempelajari selengkapnya tentang pendekatan keseluruhan untuk menyiapkan pemberitahuan Customer Insights - Journeys push, kunjungi ringkasan penyiapan pemberitahuan push.

Untuk mengaktifkan pemberitahuan Customer Insights - Journeys push, Anda harus menyelesaikan langkah-langkah berikut:

  1. Konfigurasi aplikasi pemberitahuan push
  2. Pemetaan pengguna untuk pemberitahuan push
  3. Pendaftaran perangkat untuk pemberitahuan push
  4. Menerima pemberitahuan push di perangkat
  5. Pelaporan interaksi untuk pemberitahuan push

Diagram ini menjelaskan dua langkah yang diperlukan untuk mendaftarkan perangkat dan pengguna di dalamnya Customer Insights - Journeys.

Perangkat pemberitahuan push dan diagram pendaftaran pengguna.

Pendaftaran perangkat

Untuk menyelesaikan konfigurasi aplikasi seluler, pengembang harus mendaftarkan perangkat di seluruh server. Anda seharusnya sudah memiliki token perangkat, ID pengguna dari Customer Insights - Journeys (ID kontak, ID prospek, Customer Insights - Data ID profil), dan ID aplikasi seluler dari Customer Insights - Journeys.

Setelah panggilan permintaan pendaftaran perangkat berhasil, ada respons 202. Tanggapan 202 hanya menunjukkan bahwa permintaan diterima. Untuk mengonfirmasi permintaan yang berhasil, Anda perlu memeriksa status dengan menggunakan webhook atau memanggil status titik akhir secara langsung.

API

Pendaftaran perangkat (tunggal)

Contoh permintaan HTTP (iOS):

POST {PublicEndpoint}/api/v1.0/orgs/%ORG_ID%/pushdeviceregistration/devices

{
    "MobileAppId": "00000000-0000-0000-0000-000000000000",
    "UserId": "00000000-0000-0000-0000-000000000000",
    "ApiToken": "%API_TOKEN%",
    "ApnsDeviceToken": "%APNS_TOKEN%"
}

Contoh permintaan HTTP (Android):

POST {PublicEndpoint}/api/v1.0/orgs/%ORG_ID%/pushdeviceregistration/devices

{
    "MobileAppId": "00000000-0000-0000-0000-000000000000",
    "UserId": "00000000-0000-0000-0000-000000000000",
    "ApiToken": "%API_TOKEN%",
    "FcmDeviceToken": "%FCM_TOKEN%"
}

Header:

  • x-ms-track-registration: bila benar, informasi tentang keberhasilan/kegagalan pendaftaran disimpan dan tersedia melalui API status pendaftaran.
  • x-ms-callback-url: Jika tidak kosong, pendaftaran perangkat yang gagal atau berhasil memicu webhook permintaan POST.
  • x-ms-callback-url-headers: Berisi JSON serial kamus string-ke-string, yang mewakili header yang diteruskan untuk permintaan webhook. Hanya digunakan ketika x-ms-callback-url ditentukan.

Pengembalian: 202 jika permintaan yang diberikan valid, 400 sebaliknya.

Isi respons:

Ketika x-ms-track-registration benar:

{
    "RegistrationRequestId": "%GUID%"
}

Kalau tidak, tubuh kosong.

Definisi
Nama Description
MobileAppId Pengenal aplikasi seluler yang dikonfigurasi di Customer Insights - Journeys.
UserId ID pengguna kontak, prospek, atau Customer Insights - Data profil dari Customer Insights - Journeys.
ApiToken Token API Anda untuk mengotorisasi permintaan.
ApnsDeviceToken Pengenal token perangkat unik yang iOS dihasilkan oleh aplikasi. Ini hanya akan dikirim untuk perangkat iOS
FcmDeviceToken Pengenal token perangkat unik yang Android dihasilkan oleh aplikasi. Ini hanya akan dikirim untuk perangkat Android

Pendaftaran perangkat (beberapa)

Isi pendaftaran batch berisi array hingga 100 objek yang mewakili permintaan pendaftaran perangkat.

Contoh permintaan HTTP (iOS):

POST {PublicEndpoint}/api/v1.0/orgs/%ORG_ID%/pushdeviceregistration/devices/batch

[
    {
        "MobileAppId": "00000000-0000-0000-0000-000000000000",      
        "UserId": "00000000-0000-0000-0000-000000000000",
        "ApiToken": "%API_TOKEN%",
        "ApnsDeviceToken": "%APNS_TOKEN%"
    },
    {
        "MobileAppId": "00000000-0000-0000-0000-000000000000",
        "UserId": "00000000-0000-0000-0000-000000000000",
        "ApiToken": "%API_TOKEN%",
        "ApnsDeviceToken": "%APNS_TOKEN%"
    }
]

Contoh permintaan HTTP (Android):

POST {PublicEndpoint}/api/v1.0/orgs/%ORG_ID%/pushdeviceregistration/devices/batch

[
    {
        "MobileAppId": "00000000-0000-0000-0000-000000000000",      
        "UserId": "00000000-0000-0000-0000-000000000000",
        "ApiToken": "%API_TOKEN%",
        "FcmDeviceToken": "%FCM_TOKEN%"
    },
    {
        "MobileAppId": "00000000-0000-0000-0000-000000000000",
        "UserId": "00000000-0000-0000-0000-000000000000",
        "ApiToken": "%API_TOKEN%",
        "FcmDeviceToken": "%FCM_TOKEN%"
    }
]

Header:

  • x-ms-track-registration: Jika benar, informasi tentang keberhasilan atau kegagalan pendaftaran disimpan dan tersedia melalui API status pendaftaran.
  • x-ms-callback-url: Jika tidak kosong, pendaftaran perangkat yang gagal atau berhasil memicu POST webhook permintaan.
  • x-ms-callback-url-headers: Berisi JSON serial kamus string-ke-string, yang mewakili header yang diteruskan untuk permintaan webhook. Hanya digunakan jika x-ms-callback-url didefinisikan.

Pengembalian: 202 jika permintaan yang diberikan valid, 400 sebaliknya.

Isi respons:

Ketika x-ms-track-registration benar: array item, setiap urutan item sesuai dengan urutan dari array isi permintaan.

[
    {
        "RegistrationRequestId": "%REG_REQUEST_ID%"
    },
    {
        "RegistrationRequestId": "%REG_REQUEST_ID%"
    }
]

Kalau tidak, tubuh kosong.

Status pendaftaran perangkat

POST  {PublicEndpoint}/api/v1.0/orgs/%ORG_ID%/pushdeviceregistration/devices/status/

Isi permintaan:

{
    "RegistrationRequestIds": [
        "%REG_REQUEST_ID%"
    ],
    "MobileAppId": "%MOBILE_APP_ID%",
    "ApiToken": "%API_TOKEN%"
}

Pengembalian: 200 jika permintaan yang diberikan valid, 400 sebaliknya.

Badan respons - serangkaian item:

[
    {
        "Status": "Pending|Success|Failed",
        "FailureReason": " DuplicateExists|DryRunSendingFailed|DeviceTokenTooLong|FailedToStoreDevice|ApiTokenNotValid " // dry run sending is a verification of device token by sending an invisible notification to mobile app. Such sending failure might happen due to a wrong device token or incorrect/expired mobile app auth data
    },
    {
        "Status": "Pending|Success|Failed",
        "FailureReason": " DuplicateExists|DryRunSendingFailed|DeviceTokenTooLong|FailedToStoreDevice|ApiTokenNotValid " // dry run sending is a verification of device token by sending an invisible notification to mobile app. Such sending failure might happen due to a wrong device token or incorrect/expired mobile app auth data
    }
]

Setiap pesanan item sesuai dengan urutan dari array RegistrationRequestIds .

Definisi
Nama Description
RegistrationRequestIds Array permintaan pendaftaran individu. Nilai diambil dari respons panggilan pendaftaran. Ini hanya diberikan ketika header x-ms-track-registration digunakan untuk pendaftaran
MobileAppId Pengenal aplikasi seluler yang dikonfigurasi di Customer Insights - Journeys.
UserId ID pengguna kontak, prospek, atau Customer Insights - Data profil dari Customer Insights - Journeys.

Penting

Ada tiga kemungkinan alasan mengapa status dapat terjebak dalam status "Tertunda":

  1. Permintaan pendaftaran perangkat asli memiliki token API yang tidak valid. Untuk mencegah aktor jahat melakukan serangan DoS terhadap lingkungan dengan memanggil "daftarkan perangkat" dan menghasilkan pembatasan tak terbatas, upaya tersebut tidak menghasilkan penyimpanan riwayat pendaftaran. Oleh karena itu, tidak ada informasi untuk memeriksa keberhasilan.
  2. CRM tetap dalam keadaan dibatasi selama beberapa jam, menyebabkan operasi pembaruan status gagal menjalankan tugasnya setelah beberapa kali mencoba kembali.
  3. Permintaan pendaftaran perangkat dibuat tanpa header x-ms-track-registration yang disediakan.

Webhook status pendaftaran perangkat

Jika x-ms-status-callback-url diberikan URL saat pendaftaran perangkat berhasil atau gagal, Customer Insights - Journeys mengakses nilai header.

POST ke URL yang disediakan dalam header x-ms-status-callback-url permintaan pendaftaran perangkat.

Badan:

{ 
    "Status": "Success|Failed", 
    "Signature": "%SIGNATURE%", 
    "FailureReason": " DuplicateExists|DryRunSendingFailed|DeviceTokenTooLong|FailedToStoreDevice|ApiTokenNotValid" 
}

Tip

Tanda tangan adalah hash HMACSHA256 dari URL callback yang dihitung menggunakan token API sebagai kunci. Gunakan nilai untuk memverifikasi bahwa yang Customer Insights - Journeys melakukan panggilan. Hash URL callback dengan token API di sisi webhook menggunakan algoritme yang sama dan membandingkan nilainya.

Catatan

Upaya untuk membuat permintaan terjadi sekali. Setiap kegagalan untuk menjalankan permintaan menyebabkan pemberitahuan hilang. Jenis kegagalan mencakup URL panggilan balik yang salah, batas waktu panggilan REST API, atau kode status respons yang tidak terduga.

Pengembalian: 202 jika permintaan yang diberikan valid, 400 sebaliknya.

Tubuh yang diharapkan: tubuh kosong.

Pembersihan perangkat (tunggal)

Penting untuk menghapus perangkat yang tidak lagi valid dari database untuk memastikan pengiriman pesan yang berkinerja. Gunakan pendekatan berikut untuk menghapus kombinasi perangkat, pengguna, dan aplikasi lama dari tabel perangkat.

POST {PublicEndpoint}/api/v1.0/orgs/%ORG_ID%/pushdeviceregistration/devices/cleanup

{
    "MobileAppId": "00000000-0000-0000-0000-000000000000",
    "ApiToken": "%API_TOKEN%",
    "UserId": "00000000-0000-0000-0000-000000000000",
    "DeviceToken": "%OPTIONAL_FCM_OR_APNS_DEVICE_TOKEN%"
}

Pengembalian: 202 jika permintaan yang diberikan valid, 400 sebaliknya.

Definisi
Nama Description
MobileAppId Pengenal aplikasi seluler yang dikonfigurasi di Customer Insights - Journeys.
ApiToken Token API Anda untuk mengotorisasi permintaan.
UserId ID pengguna kontak, prospek, atau Customer Insights - Data profil dari Customer Insights - Journeys.
Token Perangkat Pengenal token perangkat unik yang dihasilkan oleh aplikasi.

Pembersihan perangkat (beberapa)

Penting untuk menghapus perangkat yang tidak lagi valid dari database untuk memastikan pengiriman pesan yang berkinerja. Gunakan pendekatan berikut untuk menghapus kombinasi perangkat, pengguna, dan aplikasi lama dari tabel perangkat.

POST {PublicEndpoint}/api/v1.0/orgs/%ORG_ID%/pushdeviceregistration/devices/cleanup/batch

{
    "MobileAppId": "00000000-0000-0000-0000-000000000000",
    "ApiToken": "%API_TOKEN%",
    "UserId": "00000000-0000-0000-0000-000000000000",
    "DeviceToken": "%OPTIONAL_FCM_OR_APNS_DEVICE_TOKEN%"
}

Pengembalian: 202 jika permintaan yang diberikan valid, 400 sebaliknya.

Definisi
Nama Description
MobileAppId Pengenal aplikasi seluler yang dikonfigurasi di Customer Insights - Journeys.
ApiToken Token API Anda untuk mengotorisasi permintaan.
UserId ID pengguna kontak, prospek, atau Customer Insights - Data profil dari Customer Insights - Journeys.
Token Perangkat Pengenal token perangkat unik yang dihasilkan oleh aplikasi.