Jaa

Palveluilmoituslaitteiden rekisteröinti sovelluskehittäjille

  • Artikkeli

Lisätietoja palveluilmoitusten määrittämisestä Customer Insights - Journeysissa yleensä: palveluilmoitusten määritysten yleiskatsaus.

Jos haluat ottaa palveluilmoitukset käyttöön Customer Insights - Journeysissa, toimi seuraavasti:

  1. Palveluilmoitussovelluksen määritys
  2. Käyttäjän yhdistämismääritys palveluilmoituksia varten
  3. Laitteen rekisteröinti palveluilmoituksia varten
  4. Palveluilmoitusten vastaanotto laitteissa
  5. Vuorovaikutusraportointi palveluilmoituksia varten

Tässä kaaviossa kuvataan kaksi vaihetta, jotka tarvitaan laitteiden ja käyttäjien rekisteröintiin Customer Insights - Journeysissa.

Palveluilmoitusten laitteiden ja käyttäjien rekisteröintien kaavio.

Laitteen rekisteröiminen

Kehittäjän on rekisteröitävä laitteet eri palvelimille mobiilisovelluksen määrityksen loppuun saattamiseksi. Sinulla pitäisi olla jo laitetunnus, käyttäjätunnus Customer Insights - Journeysista (yhteyshenkilötunnus, liiditunnus, Customer Insights - Data -profiilitunnus) ja mobiilisovelluksen tunnus Customer Insights - Journeysista.

Laiterekisteröintipyynnön onnistuneeseen kutsuun tulee 202-vastaus. 202-vastaus ilmaisee vain, että pyyntö on hyväksytty. Pyynnön onnistumisen varmistamiseksi on tarkastettava sen tila käyttämällä webhookia tai kutsumalla tilapäätepistettä suoraan.

Ohjelmointirajapinta

Laitteen rekisteröinti (yksittäinen)

Esimerkki HTTP-pyynnöstä (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%"
}

Esimerkki HTTP-pyynnöstä (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%"
}

Otsikot:

  • x-ms-track-registration: Kun tämä arvo on tosi, tieto rekisteröinnin onnistumisesta/epäonnistumisesta tallennetaan, ja se on käytettävissä rekisteröintitilan ohjelmointirajapinnan kautta.
  • x-ms-callback-url: Kun tämä ei ole tyhjä, onnistunut tai epäonnistunut laitteen rekisteröinti käynnistää POST-pyynnön webhookin.
  • x-ms-callback-url-headers: Sisältää merkkijonosta merkkijonoon -sanakirjan sarjoitetun JSON-tidoston, joka edustaa webhook-pyyntöjä varten välitettyjä otsikkoja. Käytetään vain, kun x-ms-callback-url on määritetty.

Palautukset: jos 202, pyyntö on kelvollinen, muuten 400.

Vastauksen teksti:

Kun x-ms-track-registration on tosi:

{
    "RegistrationRequestId": "%GUID%"
}

Muussa tapauksessa tyhjä teksti.

Määritelmät
Nimi Kuvaus
MobileAppId Customer Insights - Journeysissa määritetyn mobiilisovelluksen tunniste.
Käyttäjätunnus Customer Insights - Journeysista peräisin olevan yhteyshenkilön, liidin tai Customer Insights - Data -profiilin käyttäjätunniste.
ApiToken Ohjelmointirajapintatunnus pyynnön hyväksymistä varten.
ApnsDeviceToken iOS-sovelluksen luoma yksilöllinen laitetunnustunniste. Tämä lähetetään vain iOS-laitteeseen
FcmDeviceToken Android-sovelluksen luoma yksilöllinen laitetunnustunniste. Tämä lähetetään vain Android-laitteeseen

Laitteen rekisteröinti (useita)

Erärekisteröinnin teksti sisältää enintään 100 laiterekisteröintipyyntöä edustavan kohteen matriisin.

Esimerkki HTTP-pyynnöstä (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%"
    }
]

Esimerkki HTTP-pyynnöstä (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%"
    }
]

Otsikot:

  • x-ms-track-registration: Kun tämä arvo on tosi, tieto rekisteröinnin onnistumisesta tai epäonnistumisesta tallennetaan, ja se on käytettävissä rekisteröintitilan ohjelmointirajapinnan kautta.
  • x-ms-callback-url: Kun tämä ei ole tyhjä, onnistunut tai epäonnistunut laitteen rekisteröinti käynnistää POST-pyynnön webhookin.
  • x-ms-callback-url-headers: Sisältää merkkijonosta merkkijonoon -sanakirjan sarjoitetun JSON-tidoston, joka edustaa webhook-pyyntöjä varten välitettyjä otsikkoja. Käytetään vain, kun x-ms-callback-url on määritetty.

Palautukset: jos 202, pyyntö on kelvollinen, muuten 400.

Vastauksen teksti:

Kun x-ms-track-registration on tosi: kohteiden matriisi, jossa kukin kohdejärjestys vastaa pyynnön tekstimatriisin järjestystä.

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

Muussa tapauksessa tyhjä teksti.

Laitteen rekisteröintitila

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

Pyynnön teksti:

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

Palautukset: jos 200, pyyntö on kelvollinen, muuten 400.

Vastauksen teksti – kohteiden matriisi:

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

Kukin kohdejärjestys vastaa RegistrationRequestIds-matriisin järjestystä.

Määritelmät
Nimi Kuvaus
RegistrationRequestIds Yksittäisten rekisteröintipyyntöjen matriisi. Arvot saadaan rekisteröintikutsujen vastauksena. Tämä annetaan vain, kun rekisteröinnissä käytettiin x-ms-track-registration-otsikkoa
MobileAppId Customer Insights - Journeysissa määritetyn mobiilisovelluksen tunniste.
Käyttäjätunnus Customer Insights - Journeysista peräisin olevan yhteyshenkilön, liidin tai Customer Insights - Data -profiilin käyttäjätunniste.

Tärkeää

Tila voi juuttua Odottaa-tilaan kolmesta eri syystä:

  1. Alkuperäisellä laitteen rekisteröintipyynnöllä oli virheellinen ohjelmointirajapintatunnus. Haitallisten toimijoiden estämiseksi kohdistamasta palvelunestohyökkäystä ympäristöön tekemällä laitteen rekisteröintikutsun ja luomalla loppumatointa rajoittamista tällaisten yritysten rekisteröintihistoriaa ei tallenneta. Siten tietoja onnistumisen tarkastamista varten ei ole.
  2. CRM pysyy rajoitetussa tilassa useita tunteja, jolloin tilanpäivitystoiminto epäonnistuu tehtävänsä suorittamisesta useiden uudelleenyritysten jälkeen.
  3. Laitteen rekisteröintipyyntö tehtiin antamatta x-ms-track-registration-otsikkoa.

Laiterekisteröinnin tilan webhook

Jos x-ms-status-callback-url on annettu URL-osoitteessa, Customer Insights - Journeys käyttää otsikon arvoa, kun laitteen rekisteröinti onnistuu tai epäonnistuu.

Suorita POST laitteen rekisteröintipyynnön x-ms-status-callback-url-otsikossa annettuun URL-osoitteeseen.

Teksti:

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

Vihje

Allekirjoitus on HMACSHA256-hajautusarvo takaisinkutsun URL-osoitteesta, joka on laskettu käyttäen ohjelmointirajapinnan tunnusta avaimena. Käytä arvoa sen varmistamiseen, että Customer Insights - Journeys suoritti kutsun. Hajauta takaisinkutsun URL-osoite ohjelmointirajapinnan tunnuksella webhookin puolella käyttäen samaa algoritmia ja vertailemalla sitten arvoja.

Muistiinpano

Pyyntö yritetään suorittaa kerran. Jos pyynnön suorittaminen epäonnistuu, ilmoitus menetetään. Virhetyyppejä ovat virheellinen takaisinkutsun URL-osoite, REST API -kutsun aikakatkaisu ja odottamaton vastauksen tilakoodi.

Palautukset: jos 202, pyyntö on kelvollinen, muuten 400.

Odotettu teksti: tyhjä teksti.

Laitteen puhdistaminen (yksittäinen)

On tärkeää poistaa tietokannasta laitteet, jotka eivät ole enää kelvollisia, jotta sanomien lähettäminen toimisi. Seuraavalla tavalla voit poistaa vanhat laite-, käyttäjä- ja sovellusyhdistelmät laitetaulukosta.

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

Palautukset: jos 202, pyyntö on kelvollinen, muuten 400.

Määritelmät
Nimi Kuvaus
MobileAppId Customer Insights - Journeysissa määritetyn mobiilisovelluksen tunniste.
ApiToken Ohjelmointirajapintatunnus pyynnön hyväksymistä varten.
Käyttäjätunnus Customer Insights - Journeysista peräisin olevan yhteyshenkilön, liidin tai Customer Insights - Data -profiilin käyttäjätunniste.
DeviceToken Sovelluksen luoma yksilöllinen laitetunnustunniste.

Laitteen puhdistaminen (useita)

On tärkeää poistaa tietokannasta laitteet, jotka eivät ole enää kelvollisia, jotta sanomien lähettäminen toimisi. Seuraavalla tavalla voit poistaa vanhat laite-, käyttäjä- ja sovellusyhdistelmät laitetaulukosta.

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

Palautukset: jos 202, pyyntö on kelvollinen, muuten 400.

Määritelmät
Nimi Kuvaus
MobileAppId Customer Insights - Journeysissa määritetyn mobiilisovelluksen tunniste.
ApiToken Ohjelmointirajapintatunnus pyynnön hyväksymistä varten.
Käyttäjätunnus Customer Insights - Journeysista peräisin olevan yhteyshenkilön, liidin tai Customer Insights - Data -profiilin käyttäjätunniste.
DeviceToken Sovelluksen luoma yksilöllinen laitetunnustunniste.