Κοινή χρήση μέσω

Καταχώριση συσκευών ειδοποίησης push για προγραμματιστές εφαρμογών

  • Άρθρο

Για να μάθετε περισσότερα σχετικά με τη συνολική προσέγγιση στη ρύθμιση ειδοποιήσεων push στο Customer Insights - Journeys, επισκεφτείτε την επισκόπηση εγκατάστασης ειδοποιήσεων push.

Για να ενεργοποιήσετε τις ειδοποιήσεις push στο Customer Insights - Journeys, θα πρέπει να ολοκληρώσετε τα παρακάτω βήματα:

  1. Ρύθμιση εφαρμογής ειδοποιήσεων push
  2. Αντιστοίχιση χρήστη για ειδοποιήσεις push
  3. Καταχώρηση συσκευής για ειδοποιήσεις push
  4. Λήψη ειδοποιήσεων push σε συσκευές
  5. Αναφορά αλληλεπίδρασης για ειδοποιήσεις push

Αυτό το διάγραμμα περιγράφει τα δύο βήματα που είναι απαραίτητα για την καταχώρηση συσκευών και χρηστών στο Customer Insights - Journeys.

Διάγραμμα καταχώρισης συσκευών και χρηστών ειδοποιήσεων push.

Καταχώρηση συσκευής

Για να ολοκληρωθεί η ρύθμιση παραμέτρων της εφαρμογής για κινητές συσκευές, ο προγραμματιστής πρέπει να καταχωρίσει συσκευές σε διακομιστές. Θα πρέπει να έχετε ήδη το διακριτικό συσκευής, το αναγνωριστικό χρήστη από το Customer Insights - Journeys (αναγνωριστικό επαφής, αναγνωριστικό υποψήφιου πελάτη, αναγνωριστικό προφίλ Customer Insights - Data) και το αναγνωριστικό εφαρμογής για κινητές συσκευές από το Customer Insights - Journeys.

Μόλις η συσκευή τηλεφωνήσει με επιτυχία, θα υπάρξει απάντηση 202. Η απάντηση 202 δηλώνει μόνο ότι η αίτηση έγινε αποδεκτή. Για να επιβεβαιώσετε μια επιτυχή αίτηση, πρέπει να ελέγξετε την κατάσταση χρησιμοποιώντας ένα webhook ή καλώντας απευθείας τελικό σημείο κατάστασης.

API

Καταχώρηση συσκευής (μεμονωμένη)

Δείγμα αιτήματος HTTP (iOS):

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

{
    "MobileAppId": "00000000-0000-0000-0000-000000000000",
    "UserId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "ApiToken": "%API_TOKEN%",
    "ApnsDeviceToken": "%APNS_TOKEN%"
}

Δείγμα αιτήματος HTTP (Android):

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

{
    "MobileAppId": "00000000-0000-0000-0000-000000000000",
    "UserId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "ApiToken": "%API_TOKEN%",
    "FcmDeviceToken": "%FCM_TOKEN%"
}

Κεφαλίδες:

  • x-ms-track-registration: όταν είναι true, οι πληροφορίες σχετικά με την επιτυχία/αποτυχία καταχώρησης αποθηκεύονται και είναι διαθέσιμες μέσω του API κατάστασης δήλωσης.
  • x-ms-callback-url: Όταν δεν είναι κενό, μια αποτυχημένη ή επιτυχημένη καταχώρηση συσκευής ενεργοποιεί το webhook αίτησης POST.
  • x-ms-callback-url-headers: Περιέχει ένα σειριοποιημένο JSON ενός λεξικό συμβολοσειράς προς συμβολοσειρά, που αντιπροσωπεύει κεφαλίδες που περνούν για αιτήσεις webhook. Χρησιμοποιείται μόνο όταν ορίζεται το x-ms-callback-url.

Επιστρέφει: 202 εάν η αίτηση που παρέχεται είναι έγκυρη, 400 διαφορετικά.

Σώμα απάντησης:

Όταν το x-ms-track-registration είναι true:

{
    "RegistrationRequestId": "%GUID%"
}

Διαφορετικά, κενό σώμα.

Ορισμοί
Ονομασία Description
MobileAppId Το αναγνωριστικό της εφαρμογής για κινητές συσκευές που έχει ρυθμιστεί στο Customer Insights - Journeys.
Αναγνωριστικό χρήστη Το αναγνωριστικό χρήστη της επαφής, του υποψήφιου πελάτη ή του προφίλ Customer Insights - Data από το Customer Insights - Journeys.
ApiToken Το διακριτικό API σας για εξουσιοδότηση της αίτησης.
ApnsDeviceToken Το μοναδικό αναγνωριστικό διακριτικού συσκευής που δημιουργείται από την εφαρμογή iOS. Αυτή η αποστολή θα γίνει μόνο για μια συσκευή iOS
FcmDeviceToken Το μοναδικό αναγνωριστικό διακριτικού συσκευής που δημιουργείται από την εφαρμογή Android. Αυτή η αποστολή θα γίνει μόνο για μια συσκευή Android

Καταχώρηση συσκευής (πολλαπλή)

Το σώμα της καταχώρησης δέσμης περιέχει έναν πίνακα έως και 100 αντικειμένων που αντιπροσωπεύει αιτήσεις καταχώρησης συσκευής.

Δείγμα αιτήματος HTTP (iOS):

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

[
    {
        "MobileAppId": "00000000-0000-0000-0000-000000000000",      
        "UserId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
        "ApiToken": "%API_TOKEN%",
        "ApnsDeviceToken": "%APNS_TOKEN%"
    },
    {
        "MobileAppId": "00000000-0000-0000-0000-000000000000",
        "UserId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
        "ApiToken": "%API_TOKEN%",
        "ApnsDeviceToken": "%APNS_TOKEN%"
    }
]

Δείγμα αιτήματος HTTP (Android):

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

[
    {
        "MobileAppId": "00000000-0000-0000-0000-000000000000",      
        "UserId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
        "ApiToken": "%API_TOKEN%",
        "FcmDeviceToken": "%FCM_TOKEN%"
    },
    {
        "MobileAppId": "00000000-0000-0000-0000-000000000000",
        "UserId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
        "ApiToken": "%API_TOKEN%",
        "FcmDeviceToken": "%FCM_TOKEN%"
    }
]

Κεφαλίδες:

  • x-ms-track-registration:: Όταν είναι true, οι πληροφορίες σχετικά με την επιτυχία ή αποτυχία καταχώρησης αποθηκεύονται και είναι διαθέσιμες μέσω του API κατάστασης δήλωσης.
  • x-ms-callback-url: Όταν δεν είναι κενό, μια αποτυχημένη ή επιτυχημένη καταχώρηση συσκευής ενεργοποιεί webhook αίτησης POST.
  • x-ms-callback-url-headers:: Περιέχει ένα σειριοποιημένο JSON ενός λεξικό συμβολοσειράς προς συμβολοσειρά, που αντιπροσωπεύει κεφαλίδες που περνούν για αιτήσεις webhook. Χρησιμοποιείται μόνο όταν ορίζεται x-ms-callback-url.

Επιστρέφει: 202 εάν η αίτηση που παρέχεται είναι έγκυρη, 400 διαφορετικά.

Σώμα απάντησης:

Όταν το x-ms-track-registration είναι true : ένας πίνακας στοιχείων, κάθε σειρά στοιχείων αντιστοιχεί στη σειρά από τον πίνακα σώματος της αίτησης.

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

Διαφορετικά, κενό σώμα.

Κατάσταση καταχώρησης συσκευής

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

Σώμα αιτήματος:

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

Επιστρέφει: 200 εάν η αίτηση που παρέχεται είναι έγκυρη, 400 διαφορετικά.

Σώμα απάντησης - ένας πίνακας στοιχείων:

[
    {
        "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
    }
]

Κάθε παραγγελία στοιχείου αντιστοιχεί στην παραγγελία από τον πίνακα RegistrationRequestIds .

Ορισμοί
Ονομασία Description
RegistrationRequestIds Ένας πίνακας μεμονωμένων αιτήσεων δήλωσης. Οι τιμές λαμβάνονται από την απόκριση των κλήσεων καταχώρησης. Αυτό παρέχεται μόνο όταν χρησιμοποιήθηκε η κεφαλίδα x-ms-track-registration για καταχώρηση
MobileAppId Το αναγνωριστικό της εφαρμογής για κινητές συσκευές που έχει ρυθμιστεί στο Customer Insights - Journeys.
Αναγνωριστικό χρήστη Το αναγνωριστικό χρήστη της επαφής, του υποψήφιου πελάτη ή του προφίλ Customer Insights - Data από το Customer Insights - Journeys.

Σημαντικό

Υπάρχουν τρεις πιθανοί λόγοι για τους οποίους η κατάσταση μπορεί να κολλήσει σε κατάσταση "Εκκρεμής":

  1. Η αίτηση καταχώρησης της αρχικής συσκευής είχε ένα μη έγκυρο διακριτικό API. Για να αποτρέψετε κακόβουλους παράγοντες να εκτελέσουν μια επίθεση DoS σε ένα περιβάλλον καλώντας "καταχώρηση συσκευής" και να δημιουργήσουν ατέρμονους περιορισμούς, αυτές οι προσπάθειες δεν παράγουν αποθήκευση του ιστορικού καταχωρήσεων. Επομένως, δεν υπάρχουν πληροφορίες για έλεγχο της επιτυχίας.
  2. Το CRM παραμένει σε περιορισμένη κατάσταση για πολλές ώρες, με αποτέλεσμα η λειτουργία ενημέρωσης κατάστασης να αποτύχει στην εκτέλεση της εργασίας του μετά από πολλές επαναλήψεις.
  3. Η αίτηση καταχώρησης συσκευής έγινε χωρίς την παρεχόμενη κεφαλίδα x-ms-track-registration .

Webhook κατάστασης καταχώρησης συσκευής

Εάν παρέχεται η διεύθυνση URL σε ένα x-ms-status-callback-url όταν η καταχώρηση συσκευής έχει αποτύχει ή επιτύχει, το Customer Insights - Journeys αποκτά πρόσβαση στην τιμή της κεφαλίδας.

ΚΑΤΑΧΩΡΗΣΗ στη διεύθυνση URL που παρέχεται εντός της κεφαλίδας x-ms-status-callback-url της αίτησης καταχώρησης συσκευής.

Σώμα:

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

Φιλοδώρημα

Η υπογραφή είναι ο κατακερματισμός HMACSHA256 της διεύθυνσης URL επιστροφής κλήσης που υπολογίζεται με χρήση του διακριτικού API ως κλειδιού. Χρησιμοποιήστε την τιμή για να επαληθεύσετε ότι το Customer Insights - Journeys έκανε την κλήση. Κατακερματίστε την διεύθυνση URL επιστροφής κλήσης με το διακριτικό API από την πλευρά του webhook, με χρήση του ίδιου αλγόριθμου και συγκρίνοντας τις τιμές.

Σημείωμα

Μια προσπάθεια να γίνει μια αίτηση συμβαίνει μία φορά. Τυχόν αποτυχία εκτέλεσης μιας αίτησης έχει ως αποτέλεσμα την απώλεια της ειδοποίησης. Οι τύποι αποτυχίας περιλαμβάνουν μια εσφαλμένη διεύθυνση URL επιστροφής κλήσης, ένα χρονικό όριο κλήσης REST API ή έναν κωδικό κατάστασης μη αναμενόμενης απάντησης.

Επιστρέφει: 202 εάν η αίτηση που παρέχεται είναι έγκυρη, 400 διαφορετικά.

Αναμενόμενο σώμα: κενό σώμα.

Εκκαθάριση συσκευής (μεμονωμένη)

Είναι σημαντικό να καταργήσετε συσκευές που δεν είναι πλέον έγκυρες από τη βάση δεδομένων, για να εξασφαλίσετε την αποστολή μηνυμάτων που εκτελούνται. Χρησιμοποιήστε την παρακάτω προσέγγιση για να καταργήσετε παλαιούς συνδυασμούς συσκευών, χρηστών και εφαρμογών από τον πίνακα συσκευών.

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

{
    "MobileAppId": "00000000-0000-0000-0000-000000000000",
    "ApiToken": "%API_TOKEN%",
    "UserId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "DeviceToken": "%OPTIONAL_FCM_OR_APNS_DEVICE_TOKEN%"
}

Επιστρέφει: 202 εάν η αίτηση που παρέχεται είναι έγκυρη, 400 διαφορετικά.

Ορισμοί
Ονομασία Description
MobileAppId Το αναγνωριστικό της εφαρμογής για κινητές συσκευές που έχει ρυθμιστεί στο Customer Insights - Journeys.
ApiToken Το διακριτικό API σας για εξουσιοδότηση της αίτησης.
Αναγνωριστικό χρήστη Το αναγνωριστικό χρήστη της επαφής, του υποψήφιου πελάτη ή του προφίλ Customer Insights - Data από το Customer Insights - Journeys.
DeviceToken Το μοναδικό αναγνωριστικό διακριτικού συσκευής που δημιουργείται από την εφαρμογή.

Εκκαθάριση συσκευής (πολλαπλή)

Είναι σημαντικό να καταργήσετε συσκευές που δεν είναι πλέον έγκυρες από τη βάση δεδομένων, για να εξασφαλίσετε την αποστολή μηνυμάτων που εκτελούνται. Χρησιμοποιήστε την παρακάτω προσέγγιση για να καταργήσετε παλαιούς συνδυασμούς συσκευών, χρηστών και εφαρμογών από τον πίνακα συσκευών.

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

{
    "MobileAppId": "00000000-0000-0000-0000-000000000000",
    "ApiToken": "%API_TOKEN%",
    "UserId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "DeviceToken": "%OPTIONAL_FCM_OR_APNS_DEVICE_TOKEN%"
}

Επιστρέφει: 202 εάν η αίτηση που παρέχεται είναι έγκυρη, 400 διαφορετικά.

Ορισμοί
Ονομασία Description
MobileAppId Το αναγνωριστικό της εφαρμογής για κινητές συσκευές που έχει ρυθμιστεί στο Customer Insights - Journeys.
ApiToken Το διακριτικό API σας για εξουσιοδότηση της αίτησης.
Αναγνωριστικό χρήστη Το αναγνωριστικό χρήστη της επαφής, του υποψήφιου πελάτη ή του προφίλ Customer Insights - Data από το Customer Insights - Journeys.
DeviceToken Το μοναδικό αναγνωριστικό διακριτικού συσκευής που δημιουργείται από την εφαρμογή.