Wil je het gedrag van je klanten opvolgen met het best passende kanaal? Of segmenten maken op basis van gedrag? Met dee integratie is het mogelijk om alle e-mail, push, in app, inbox en SMS activiteiten op klantniveau dagelijks op te halen via onze REST API.
Om de REST API te gebruiken is ook Oauth 2.0 app benodigd om te kunnen authenticeren met de REST API.
| Retentie tot 1 jaar De Analytics Events API koppelt maximaal de data terug tot 1 jaar in het verleden. |
Installatie in de Store
Via de Store kan de app eenvoudig worden geactiveerd, dit zorgt ervoor dat de REST API beschikbaar komt voor de betreffende brand;
De wizard bestaat maar uit 1 stap, namelijk het opgeven van eventuele financiële gegevens.
Oauth2.0
De Analytics Event API vereist Oauth2.0 authenticatie op basis van Client Credentials, dit kan geconfigureerd worden via de Oauth 2.0 app in de store. Ga naar Integrations > App:
Dit opent een dialoog, vul deze in en bevestig het dialoog:
Scope
De scope Analytics Events lezen is benodigd voor het ophalen van de Analytics Events, deze wordt straks bij het aanroepen van de API meegegeven als; analytics.events:read
Omleidings-URL
De omleidings-URL is benodigd om de Oauth flow af te kunnen ronden en "authorization code" te kunnen ontvangen.
Na het bevestigen wordt de Client ID en en eenmalig de Client Secret getoond, deze zijn benodigd voor het opzetten van de verbinding;
Client Secret
De Client Secret wordt eenmalig getoond, in het geval dat deze niet meer bekend is zal een nieuwe app aangemaakt moeten worden in deze interface om een nieuwe Client Secret te bemachtigen.
De Client Credentials kunnen gebruikt worden om een token aan te vragen bij https://auth.clang.cloud/oauth2/token, zie bijvoorbeeld het onderstaand voorbeeld in Postman:
Analytics Events REST API
Met de Analytics API is het mogelijk om events op te halen tussen een opgegeven start- en einddatum. Daarbij zijn de gegevens beschikbaar sinds en kan er maximaal tot 24 maanden in het verleden gegevens worden opgehaald.
Response Events API Bron uitklappen
Parameters
De volgende parameters worden ondersteund bij het aanroepen van het endpoint
Param | Verplicht | Toelichting |
|---|---|---|
| filter[date_from] | Ja | De startdatum van de events welke je wilt ophalen uit de API, met een maximum van 1 jaar in het verleden. Formaat: YYYY-mm-dd |
| filter[date_to] | Ja | De einddatum van de events welke je wilt ophalen uit de API. Formaat: YYYY-mm-dd |
| filter[metric] | Nee | De mogelijkheid om het response te beperken tot een specifieke metric;
|
| limit | Nee | Het maximaal aantal events welke terug worden gekoppeld in de response. Maximaal: 1.000 |
| offset | Nee | De offset van de events collectie welke opgehaald wordt. Standaard: 0 |
Paginering
De response van de events API koppelt altijd een `total_count` terug van het aantal gevonden resultaten. In het geval dat er meer events beschikbaar zijn dan het gekozen limiet, dan zal het element `_links` de endpoint bevatten van de huidige, laatste en volgende endpoint.
Zie het voorbeeld hieronder;
| Paginering voorbeeld |
|---|
| { "total_count": 466, "_links": { "current": "https://api.canopydeploy.net/analytics-events/events?filter[date_from]=2023-01-01&filter[date_to]=2023-01-25&limit=100&offset=0", "last": "https://api.canopydeploy.net/analytics-events/events?filter[date_from]=2023-01-01&filter[date_to]=2023-01-25&limit=100&offset=400", "next": "https://api.canopydeploy.net/analytics-events/events?filter[date_from]=2023-01-01&filter[date_to]=2023-01-25&limit=100&offset=100" }, "data": [] } |
Data velden
Hieronder een toelichting van de data velden in de response van de events API:
Veldnaam | Toelichting | Voorbeeld waarde |
|---|---|---|
| bounce_category | In het geval van een bounces metric wordt de bounce category hierin aangegeven | |
| bounce_code | In het geval van een bounces metric wordt de bounce code hierin aangegeven | |
| bounce_type | In het geval van een bounces metric wordt de bounce type hierin aangegeven | |
| brand_id | Numerieke waarde van de brand_id waarvoor de events worden opgehaald, deze waarde is uniek per portal | 54 |
| brand_name | De naam van de brand, zoals ingesteld in de applicatie | Deployteq Testomgeving |
| broadcast_event_sub_type | Sub type:
| CAMPAIGN |
| broadcast_event_type | Event type:
| |
| broadcast_id | Unieke identificatie per portal van een verzending | 6631 |
| broadcast_manual_options | Verzendingsvariabelen welke zijn meegegeven voor de gehele selectie in de verzending. Deze variabelen kunnen aangemaakt worden in de content, bijvoorbeeld: {{manual field="Voorbeeld"}} | { "CustomerCount": 10, "data": "Campagne mail" } |
| broadcast_metadata | Persoonlijke verzendingsvariabelen welke zijn meegegeven in de verzending. Deze variabelen kunnen aangemaakt worden in de content, bijvoorbeeld: {{meta field="Voorbeeld"}} | { } |
| broadcast_timestamp | De verzenddatum en tijd van de broadcast: YYYY-mm-ddTHH:mm:ss+Tijdzone | 2023-01-28T11:31:41+01:00 |
| broadcast_type | Broadcast type:
| |
| campaign_id | Unieke ID van de verzendende campagne, welke 0 is in het geval van een SINGLEMAIL. | 17 |
| campaign_name | De campagne naam binnen de applicatie | Daily send |
| campaign_object_id | Het campagne object id welke verantwoordelijk is voor de verzending, deze is 0 in het geval van een SINGLEMAIL. | 3 |
| content_id | Het ID van de e-mail content vanuit de applicatie | 593 |
| content_name | De naam van de e-mail content welke is gebruikt in de verzending | Wekelijkse nieuwsbrief |
| customer_email_address | Het e-mailadres van de klant waarvoor de mail gerenderd, dit hoeft niet persé de ontvanger van de e-mail te zijn als een override is ingesteld. | angelovanderkleij@deployteq.com |
| customer_id | Brand uniek ID voor het klantrecord in Deployteq | 103 |
| email_address | Het e-mailadres waar de e-mail naartoe verstuurd wordt. | angelovanderkleij@deployteq.com |
| email_address_override | Deze parameter geeft aan of een override was ingesteld voor de verzending. Een override kan worden ingesteld om de verzending te testen, daarbij wordt de e-mail gerenderd op basis van geselecteerde klant. De verzending wordt uiteindelijk gedaan naar het e-mailadres welke ingesteld staat als override. Mogelijke waardes; 0 → Geen override 1 → Ja, een override is ingesteld | 0 |
| email_domain | Het domein van het ontvangende e-mailadres | deployteq.com |
| external_id | Het standaard systeemveld klantnummer waarin bijvoorbeeld jullie eigen CRM ID of GUID in opgeslagen kan worden | 42560 |
| ip_address | Het Ip-adres waarop een opens of clicks metric heeft plaats gevonden, bij andere metrics is deze waarde null | |
| link_id | Het unieke ID van een link in de verzending, deze is alleen gevuld bij een clicks metric | |
| machine_generated | Een boolean met daarin de status of een opens metric door een ISP (Machine generated) of menselijk handen is ontstaan:
| false |
| mailing_type | Per brand zijn een aantal standaard mailingtypes gedefinieerd, welke door de brand beheerders uitgebreid kan worden. Per verzending kan een mailing type worden geselecteerd om de verzendingen te kunnen segmenteren. | promotional mail |
| metric | De event metric welke wordt teruggekoppeld en waarop met filters het response beperkt kan worden van deze API. Mogelijke metrics;
| broadcasts |
| metric_id | 0 | |
| metric_timestamp | De datum- en tijd van dat de metric is geregistreerd; YYYY-mm-ddTHH:mm:ss+Tijdzone | 2023-01-28T11:31:41+01:00 |
| original_content_id | ||
| original_new_content_id | ||
| portal_id | Unieke identificatie van de portal | 1746 |
| portal_name | Unieke naam van de portal | Deployteq |
| subject | Onderwerp van de verzending Let op; alleen het onderwerp van de metric broadcast wordt volledig gerenderd aangeleverd. De andere metrics kunnen Smarty tags bevatten. | Test email 2023-01-24 |
| test_mailing | De status van het test verzending vinkje welke ingesteld kan worden bij het opstellen van de verzending.
| 0 |
| ua_brand | Informatie van het device, OS en browser bij een opens of clicks | Apple |
| ua_clientinfo_engine | Informatie van het device, OS en browser bij een opens of clicks | Blink |
| ua_clientinfo_engine_version | Informatie van het device, OS en browser bij een opens of clicks | |
| ua_clientinfo_name | Informatie van het device, OS en browser bij een opens of clicks | Chrome |
| ua_clientinfo_short_name | Informatie van het device, OS en browser bij een opens of clicks | CH |
| ua_clientinfo_type | Informatie van het device, OS en browser bij een opens of clicks | browser |
| ua_clientinfo_version | Informatie van het device, OS en browser bij een opens of clicks | 109.0 |
| ua_device | Informatie van het device, OS en browser bij een opens of clicks | desktop |
| ua_model | Informatie van het device, OS en browser bij een opens of clicks | |
| ua_osinfo_name | Informatie van het device, OS en browser bij een opens of clicks | Mac |
| ua_osinfo_platform | Informatie van het device, OS en browser bij een opens of clicks | |
| ua_osinfo_short_name | Informatie van het device, OS en browser bij een opens of clicks | MAC |
| ua_osinfo_version | Informatie van het device, OS en browser bij een opens of clicks | 10.15 |
| url | In het geval van een clicks metric zal hierin de gepersonaliseerde URL worden opgeleverd. Let op: De standaard variabele zoals {{viewurl}} en {{unsubscribe}} worden altijd als een smarty tag teruggekoppeld. | |
| url_unrendered | In het geval van een clicks metric zal hierin de niet gerenderde URL worden teruggekoppeld, deze bevat mogelijk Smarty tags | |
| uuid | Unieke GUID voor het event | 148a0d9b-e138-4b9b-89e3-3c37a8f5d53b |
Limitering
De API is beperkt tot 50.000 verzoeken per brand per dag.
Responses
De volgende statussen kunnen door de API worden teruggegeven;
HTTP statuscode | HTTP message |
|---|---|
200 | Successful request |
400 | Bad request |
401 | Unauthorized |
| 403 | Forbidden |
404 | Not found |
429 | Too Many Requests |
500 | Internal Server Error |