Delen via

Apparaatregistratie voor pushmeldingen voor toepassingsontwikkelaars

  • Artikel

Voor meer informatie over de algemene aanpak voor het instellen van pushmeldingen in Customer Insights - Journeys, gaat u naar het overzicht voor het instellen van pushmeldingen.

Als u pushmeldingen in Customer Insights - Journeys wilt inschakelen, moet u de volgende stappen uitvoeren:

  1. Configuratie van de toepassing voor pushmeldingen
  2. Gebruikerstoewijzing voor pushmeldingen
  3. Apparaatregistratie voor pushmeldingen
  4. Pushmeldingen ontvangen op mobiele apparaten
  5. Interacties voor pushmeldingen rapporteren

Dit diagram beschrijft de twee stappen die nodig zijn om apparaten en gebruikers binnen Customer Insights - Journeys te registreren.

Apparaat voor pushmeldingen en diagram voor gebruikersregistratie.

Apparaatregistratie

Om de configuratie van de mobiele app te voltooien, moet de ontwikkelaar apparaten op verschillende servers registreren. Als het goed is, heeft u het apparaattoken al en de gebruikers-id van Customer Insights - Journeys (contact-id, lead-id, Customer Insights - Data-profiel-id) en de mobiele toepassings-id van Customer Insights - Journeys.

Na een succesvolle aanroep van een aanvraag voor apparaatregistratie, volgt er een 202-respons. De 202-respons geeft alleen aan dat de aanvraag is geaccepteerd. Om een geslaagde aanvraag te bevestigen, moet u de status controleren door een webhook te gebruiken of het statuseindpunt rechtstreeks aan te roepen.

API

Apparaatregistratie (enkel)

Voorbeeld HTTP-aanvraag (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%"
}

Voorbeeld HTTP-aanvraag (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%"
}

Kopteksten:

  • x-ms-track-registration: indien waar wordt de informatie over het slagen/mislukken van de registratie opgeslagen en is deze beschikbaar via de API voor registratiestatussen.
  • x-ms-callback-url: indien niet leeg, activeert een mislukte of geslaagde apparaatregistratie de webhook POST-aanvraag.
  • x-ms-callback-url-headers: bevat een geserialiseerde JSON van een string-naar-string-woordenboek, voor headers die zijn doorgegeven voor webhookverzoeken. Wordt alleen gebruikt als x-ms-callback-url is gedefinieerd.

Retourneert: 202 als de verstrekte aanvraag geldig is, anders 400.

Hoofdtekst van respons:

Wanneer x-ms-track-registration waar is:

{
    "RegistrationRequestId": "%GUID%"
}

Anders een lege hoofdtekst.

Definities
Meting Omschrijving
MobileAppId De id van de mobiele toepassing die in Customer Insights - Journeys is geconfigureerd.
Gebruikers-id De gebruikers-id van de contactpersoon, lead of het Customer Insights - Data-profiel van Customer Insights - Journeys.
ApiToken Uw API-token om de aanvraag te autoriseren.
ApnsDeviceToken De unieke apparaattoken-id die door de iOS-toepassing is gegenereerd. Deze wordt alleen verzonden voor een iOS-apparaat
FcmDeviceToken De unieke apparaattoken-id die door de Android-toepassing is gegenereerd. Deze wordt alleen verzonden voor een Android-apparaat

Apparaatregistratie (meerdere)

De hoofdtekst van de batchregistratie bevat een matrix van maximaal 100 objecten die aanvragen voor apparaatregistratie vertegenwoordigen.

Voorbeeld HTTP-aanvraag (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%"
    }
]

Voorbeeld HTTP-aanvraag (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%"
    }
]

Kopteksten:

  • x-ms-track-registration: indien waar wordt de informatie over het slagen of mislukken van de registratie opgeslagen en is deze beschikbaar via de API voor registratiestatussen.
  • x-ms-callback-url: indien niet leeg, activeert een mislukte of geslaagde apparaatregistratie een webhook POST-aanvraag.
  • x-ms-callback-url-headers: bevat een geserialiseerde JSON van een string-naar-string-woordenboek, voor headers die zijn doorgegeven voor webhookaanvragen. Wordt alleen gebruikt wanneer x-ms-callback-url is gedefinieerd.

Retourneert: 202 als de verstrekte aanvraag geldig is, anders 400.

Hoofdtekst van respons:

Wanneer x-ms-track-registration waar is: een matrix van items, elke itemorder komt overeen met de order uit de matrix van de aanvraagbody.

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

Anders een lege hoofdtekst.

Registratiestatus van apparaat

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

Aanvraagbody:

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

Retourneert: 200 als de verstrekte aanvraag geldig is, anders 400.

Hoofdtekst van respons, een matrix van items:

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

Elk itemorder komt overeen met de order van de matrix RegistrationRequestIds.

Definities
Meting Omschrijving
RegistrationRequestIds Een matrix met individuele registratieverzoeken. De waarden zijn afkomstig uit de respons van de registratieoproepen. Dit wordt alleen verstrekt als de header x-ms-track-registration is gebruikt voor registratie
MobileAppId De id van de mobiele toepassing die in Customer Insights - Journeys is geconfigureerd.
Gebruikers-id De gebruikers-id van de contactpersoon, lead of het Customer Insights - Data-profiel van Customer Insights - Journeys.

Belangrijk

Er zijn drie mogelijke redenen waarom de status vastloopt bij de status 'In behandeling':

  1. De oorspronkelijke aanvraag voor apparaatregistratie bevatte een ongeldig API-token. Om te voorkomen dat kwaadwillenden een DoS-aanval op een omgeving uitvoeren door 'register device' aan te roepen en oneindige beperkingen te genereren, zorgen dergelijke pogingen er niet voor dat de registratiegeschiedenis wordt opgeslagen. Daardoor is er geen informatie om te controleren of het gelukt is.
  2. De CRM blijft gedurende meerdere uren in een beperkte status, waardoor de bewerking van statusupdates na meerdere nieuwe pogingen mislukt.
  3. De aanvraag voor apparaatregistratie is zonder de x-ms-track-registration verstrekte header gedaan.

Webhook voor status van apparaatregistratie

Als een x-ms-status-callback-url is geleverd bij de URL wanneer een apparaatregistratie geslaagd of mislukt is, heeft Customer Insights - Journeys toegang tot de waarde van de header.

POST naar de URL die in de header x-ms-status-callback-url van de aanvraag voor apparaatregistratie is opgegeven.

Tekst:

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

Fooi

De handtekening is de HMACSHA256-hash van de callback-URL, berekend met behulp van de API-token als sleutel. Gebruik de waarde om te verifiëren of Customer Insights - Journeys de aanroep heeft gedaan. Hash de callback-URL met het API-token aan de zijde van de webhook, met behulp van hetzelfde algoritme en vergelijken van de waarden.

Opmerking

Een poging tot het doen van een aanvraag gebeurt eenmalig. Als een aanvraag niet wordt uitgevoerd, gaat de melding verloren. Fouttypen zijn onder meer een onjuiste callback-URL, een time-out van een REST API-aanroep of een onverwachte responsstatuscode.

Retourneert: 202 als de verstrekte aanvraag geldig is, anders 400.

Verwachte tekst: lege tekst.

Apparaatopschoning (enkel)

Het is belangrijk om apparaten die niet langer geldig zijn uit de database te verwijderen om verzending van berichten goed te laten werken. Gebruik de volgende aanpak om oude combinaties van apparaat, gebruiker en applicatie uit de apparatentabel te verwijderen.

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%"
}

Retourneert: 202 als de verstrekte aanvraag geldig is, anders 400.

Definities
Meting Omschrijving
MobileAppId De id van de mobiele toepassing die in Customer Insights - Journeys is geconfigureerd.
ApiToken Uw API-token om de aanvraag te autoriseren.
Gebruikers-id De gebruikers-id van de contactpersoon, lead of het Customer Insights - Data-profiel van Customer Insights - Journeys.
DeviceToken De unieke apparaattoken-id die door de toepassing is gegenereerd.

Apparaatopschoning (meerdere)

Het is belangrijk om apparaten die niet langer geldig zijn uit de database te verwijderen om verzending van berichten goed te laten werken. Gebruik de volgende aanpak om oude combinaties van apparaat, gebruiker en applicatie uit de apparatentabel te verwijderen.

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%"
}

Retourneert: 202 als de verstrekte aanvraag geldig is, anders 400.

Definities
Meting Omschrijving
MobileAppId De id van de mobiele toepassing die in Customer Insights - Journeys is geconfigureerd.
ApiToken Uw API-token om de aanvraag te autoriseren.
Gebruikers-id De gebruikers-id van de contactpersoon, lead of het Customer Insights - Data-profiel van Customer Insights - Journeys.
DeviceToken De unieke apparaattoken-id die door de toepassing is gegenereerd.