Wil je het gedrag van je klanten opvolgen met het best passende kanaal? Of segmenten maken op basis van gedrag? Met deze 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 uit maar 1 stap, namelijk het opgeven van eventuele financiële gegevens:

 


Oauth2.0 app configureren

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 > Apps en creëer een nieuwe 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 12 maanden in het verleden gegevens worden opgehaald. 

Endpoint: https://api.canopydeploy.net/analytics-events/events?filter[date_from]={{date_from}}&filter[date_to]={{date_to}}


Response Events API 
{
    "total_count": 36,
    "_links": {
        "current": "https://api.canopydeploy.net/analytics-events/events?filter%5Bdate_from%5D=2023-01-24&filter%5Bdate_to%5D=2023-01-25&limit=100&offset=0"
    },
    "data": [
        {
            "bounce_category": null,
            "bounce_code": null,
            "bounce_type": null,
            "brand_id": 54,
            "brand_name": "Deployteq Testomgeving",
            "broadcast_event_sub_type": "CAMPAIGN",
            "broadcast_event_type": "EMAIL",
            "broadcast_id": 6631,
            "broadcast_manual_options": {
                "CustomerCount": 10,
                "data": "Campagne mail"
            },
            "broadcast_metadata": {
                "language": "nl",
                "selectionId": "623862315"
            },
            "broadcast_timestamp": "2023-01-28T11:31:41+01:00",
            "broadcast_type": "MAIL",
            "campaign_id": 17,
            "campaign_name": "Daily send",
            "campaign_object_id": 3,
            "content_id": 593,
            "content_name": "Wekelijkse nieuwsbrief",
            "customer_email_address": "angelovanderkleij@deployteq.com",
            "customer_id": 103,
            "email_address": "angelovanderkleij@deployteq.com",
            "email_address_override": 0,
            "email_domain": "deployteq.com",
            "external_id": "42560",
            "ip_address": null,
            "link_id": null,
            "machine_generated": false,
            "mailing_type": "promotional mail",
            "metric": "broadcasts",
            "metric_id": 0,
            "metric_timestamp": "2023-01-28T11:31:41+01:00",
            "original_content_id": 528,
            "original_new_content_id": 378,
            "portal_id": 1746,
            "portal_name": "Deployteq",
            "subject": "Test email 2023-01-24",
            "test_mailing": 0,
            "ua_brand": null,
            "ua_clientinfo_engine": null,
            "ua_clientinfo_engine_version": null,
            "ua_clientinfo_name": null,
            "ua_clientinfo_short_name": null,
            "ua_clientinfo_type": null,
            "ua_clientinfo_version": null,
            "ua_device": null,
            "ua_model": null,
            "ua_osinfo_name": null,
            "ua_osinfo_platform": null,
            "ua_osinfo_short_name": null,
            "ua_osinfo_version": null,
            "url": null,
            "url_unrendered": null,
            "uuid": "148a0d9b-e138-4b9b-89e3-3c37a8f5d53b"
        },
        {
            "bounce_category": null,
            "bounce_code": null,
            "bounce_type": null,
            "brand_id": 54,
            "brand_name": "Deployteq Testomgeving",
            "broadcast_event_sub_type": "CAMPAIGN",
            "broadcast_event_type": "EMAIL",
            "broadcast_id": 6631,
            "broadcast_manual_options": {
                "CustomerCount": 10,
                "data": "Campagne mail"
            },
            "broadcast_metadata": {
                "language": "nl",
                "selectionId": "623862315"
            },
            "broadcast_timestamp": "2023-01-28T11:31:41+01:00",
            "broadcast_type": "MAIL",
            "campaign_id": 17,
            "campaign_name": "Daily send",
            "campaign_object_id": 3,
            "content_id": 593,
            "content_name": "Wekelijkse nieuwsbrief",
            "customer_email_address": "angelovanderkleij@deployteq.com",
            "customer_id": 103,
            "email_address": "angelovanderkleij@deployteq.com",
            "email_address_override": 0,
            "email_domain": "deployteq.com",
            "external_id": "42560",
            "ip_address": "45.118.251.216",
            "link_id": 24964,
            "machine_generated": false,
            "mailing_type": "",
            "metric": "clicks",
            "metric_id": 1374,
            "metric_timestamp": "2023-01-28T22:10:36+01:00",
            "original_content_id": 528,
            "original_new_content_id": 378,
            "portal_id": 1746,
            "portal_name": "Deployteq",
            "subject": "Test email 2023-01-24",
            "test_mailing": 0,
            "ua_brand": "Apple",
            "ua_clientinfo_engine": "Blink",
            "ua_clientinfo_engine_version": "",
            "ua_clientinfo_name": "Chrome",
            "ua_clientinfo_short_name": "CH",
            "ua_clientinfo_type": "browser",
            "ua_clientinfo_version": "109.0",
            "ua_device": "desktop",
            "ua_model": "",
            "ua_osinfo_name": "Mac",
            "ua_osinfo_platform": "",
            "ua_osinfo_short_name": "MAC",
            "ua_osinfo_version": "10.15",
            "url": "{{viewurl}}",
            "url_unrendered": "{{viewurl}}",
            "uuid": "bd6bf1cd-3a55-4f5b-9f98-a5ec341e52dd"
        },
        {
            "bounce_category": null,
            "bounce_code": null,
            "bounce_type": null,
            "brand_id": 54,
            "brand_name": "Deployteq Testomgeving",
            ""broadcast_event_sub_type": "CAMPAIGN",
            "broadcast_event_type": "EMAIL",
            "broadcast_id": 6631,
            "broadcast_manual_options": {
                "CustomerCount": 10,
                "data": "Campagne mail"
            },
            "broadcast_metadata": {
                "language": "nl",
                "selectionId": "623862315"
            },
            "broadcast_timestamp": "2023-01-28T11:31:41+01:00",
            "broadcast_type": "MAIL",
            "campaign_id": 17,
            "campaign_name": "Daily send",
            "campaign_object_id": 3,
            "content_id": 593,
            "content_name": "Wekelijkse nieuwsbrief",
            "customer_email_address": "angelovanderkleij@deployteq.com",
            "customer_id": 103,
            "email_address": "angelovanderkleij@deployteq.com",
            "email_address_override": 0,
            "email_domain": "deployteq.com",
            "external_id": "42560",
            "ip_address": "45.118.251.216",
            "link_id": null,
            "machine_generated": false,
            "mailing_type": "",
            "metric": "opens",
            "metric_id": 1487,
            "metric_timestamp": "2023-01-28T22:10:36+01:00",
            "original_content_id": 528,
            "original_new_content_id": 378,
            "portal_id": 1746,
            "portal_name": "Deployteq",
            "subject": "Test email 2023-01-24",
            "test_mailing": 0,
            "ua_brand": "Apple",
            "ua_clientinfo_engine": "Blink",
            "ua_clientinfo_engine_version": "",
            "ua_clientinfo_name": "Chrome",
            "ua_clientinfo_short_name": "CH",
            "ua_clientinfo_type": "browser",
            "ua_clientinfo_version": "109.0",
            "ua_device": "desktop",
            "ua_model": "",
            "ua_osinfo_name": "Mac",
            "ua_osinfo_platform": "",
            "ua_osinfo_short_name": "MAC",
            "ua_osinfo_version": "10.15",
            "url": null,
            "url_unrendered": null,
            "uuid": "766ef52a-4b54-4c38-9fa8-d4bdf9127fa5"
        }
    ]
}

Parameters

De volgende parameters worden ondersteund bij het aanroepen van het endpoint

ParamVerplichtToelichting
filter[date_from]Ja

De startdatum van de events welke je wilt ophalen uit de API, met een maximum tot 1 jaar in het verleden.

Formaat: YYYY-mm-dd 

filter[date_to]Ja

De einddatum van de events die je wil ophalen uit de API.

Formaat: YYYY-mm-dd 

filter[metric]Nee

De mogelijkheid om het response te beperken tot een specifieke metric;

  • broadcasts
  • opens
  • clicks
  • short_links
  • bounces
  • complaints
limitNee

Het maximaal aantal events welke terug worden gekoppeld in de response.

Maximaal: 1.000

offsetNee

De offset van de eventscollectie die opgehaald wordt. 

Standaard: 0

filter[metric]

Als je filter op een specifieke metric set, wees dan bewust dat alleen de gegevens worden opgehaald in het opgegeven tijdsbereik. Dus stel dat je de opens of clicks metric ophaalt, dan zijn dit niet het totaal aantal opens/clicks van de verzending, maar beperkt tot de geregistreerde opens/clicks in het opgegeven tijdsbereik.

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:

VeldnaamToelichtingVoorbeeld waarde
bounce_categoryIn het geval van een bounces metric wordt de bounce category hierin aangegeven
bounce_codeIn het geval van een bounces metric wordt de bounce code hierin aangegeven
bounce_typeIn het geval van een bounces metric wordt de bounce type hierin aangegeven
brand_idNumerieke waarde van de brand_id waarvoor de events worden opgehaald, deze waarde is uniek per portal54
brand_nameDe naam van de brand, zoals ingesteld in de applicatieDeployteq Testomgeving
broadcast_event_sub_type

Sub type:

  • CAMPAIGN
  • QUICKMAIL
  • SINGLEMAIL
  • SPLITRUN
  • SMARTRUN
  • SINGLESMS
  • QUICKSMS
CAMPAIGN
broadcast_event_type

Event type:

  • EMAIL 
  • QUICKMAIL
  • SINGLEMAIL
  • SPLITRUNPART
  • SPLITRUNWINNER
  • IN_APP_MESSAGE_SINGLE
  • IN_APP_MESSAGE_BATCH
  • PUSH_NOTIFICATION_SINGLE
  • PUSH_NOTIFICATION_BATCH
  • INBOX_MESSAGE
  • SINGLESMS
  • QUICKSMS
EMAIL
broadcast_idUnieke identificatie per portal van een verzending6631
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:

{{$metadata['key'] = 'Voorbeeld'}}

{
    "language": "nl"

}

broadcast_timestampDe verzenddatum en tijd van de broadcast: YYYY-mm-ddTHH:mm:ss+Tijdzone2023-01-28T11:31:41+01:00
broadcast_type

Broadcast type:

  • MAIL
  • IN_APP_MESSAGE
  • PUSH_NOTIFICATION
  • INBOX_MESSAGE
  • SMS
MAIL
campaign_idUnieke ID van de verzendende campagne, welke 0 is in het geval van een SINGLEMAIL.17
campaign_nameDe campagne naam binnen de applicatieDaily send
campaign_object_idHet campagne object id welke verantwoordelijk is voor de verzending, deze is 0 in het geval van een SINGLEMAIL.3
content_id

Het unieke ID van een content

* In het geval van een email content kan het beste gewerkt worden met het veld 'original_new_content_id' om data te groeperen per content

593
content_nameDe naam van de e-mail content welke is gebruikt in de verzendingWekelijkse nieuwsbrief
customer_email_addressHet 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_idBrand uniek ID voor het klantrecord in Deployteq103
email_addressHet 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_domainHet domein van het ontvangende e-mailadresdeployteq.com
external_idHet standaard systeemveld klantnummer waarin bijvoorbeeld jullie eigen CRM ID of GUID in opgeslagen kan worden 42560
ip_addressHet Ip-adres waarop een opens of clicks metric heeft plaats gevonden, bij andere metrics is deze waarde null
link_idHet 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:

  • true: Open is gegenereerd door een machine
  • false: Mensenlijk handelen 
false
mailing_typePer 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 staan hieronder vermeld;

  • broadcasts
  • opens
  • clicks
  • short_links
  • bounces
  • complaints


Totaal aantal kliks

Als de wens is om het totaal aantal kliks van een mailing op te halen, dan zullen de metrics clicks en short_links bij elkaar opgeteld moeten worden.

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_idHet unieke ID van een e-mail content, deze wordt ook gebruikt in de interface als de content wordt geopend. Dit ID kan gebruikt worden in rapportages om de gegevens per content te groeperen.
portal_idUnieke identificatie van de portal1746
portal_nameUnieke naam van de portalDeployteq
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: Test mailing is niet gezet
  • 1: Test mailing vinkje is gezet
0
ua_brandInformatie van het device, OS en browser bij een opens of clicksApple
ua_clientinfo_engineInformatie van het device, OS en browser bij een opens of clicksBlink
ua_clientinfo_engine_versionInformatie van het device, OS en browser bij een opens of clicks
ua_clientinfo_nameInformatie van het device, OS en browser bij een opens of clicksChrome
ua_clientinfo_short_nameInformatie van het device, OS en browser bij een opens of clicksCH
ua_clientinfo_typeInformatie van het device, OS en browser bij een opens of clicksbrowser
ua_clientinfo_versionInformatie van het device, OS en browser bij een opens of clicks109.0
ua_deviceInformatie van het device, OS en browser bij een opens of clicksdesktop
ua_modelInformatie van het device, OS en browser bij een opens of clicks
ua_osinfo_nameInformatie van het device, OS en browser bij een opens of clicksMac
ua_osinfo_platformInformatie van het device, OS en browser bij een opens of clicks
ua_osinfo_short_nameInformatie van het device, OS en browser bij een opens of clicksMAC
ua_osinfo_versionInformatie van het device, OS en browser bij een opens of clicks10.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_unrenderedIn het geval van een clicks metric zal hierin de niet gerenderde URL worden teruggekoppeld, deze bevat mogelijk Smarty tags
uuidUnieke GUID voor het event148a0d9b-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 statuscodeHTTP message

200 

Successful request

400 

Bad request

401 

Unauthorized
403 Forbidden

404 

Not found

429 

Too Many Requests

500 

Internal Server Error

Reponse 429 - extra toelichting

Om de stabiliteit van onze API te garanderen hebben wij extra rate limiting toegevoegd op de infrastructuur. Dit betreft het maximale aantal calls per ip of per token. Op de REST API gelden 2 vormen van rate limiting. Beide types staan hieronder toegelicht. Rate limiting wordt toegepast om het verkeer vanuit externe systemen te doseren en het Deployteq platform te beschermen tegen grote/plotselinge belasting op de REST API & Deployteq systemen.

Type: Aantal connecties per ip

  • Een IP adres mag maximaal 20 connecties opzetten per Deployteq proxy. De 21e connectie zal simpelweg worden geweigerd. Op het moment zijn er vier Deployteq proxy's actief, wat in praktijk zou betekenen dat per IP max (4*20) 80 connecties tegelijk opgezet kan worden. Deze rate limit wordt bijna nooit geraakt, maar is er puur voor extra veiligheid. 

Type: Aantal calls per token of IP adres 

  • Een token mag maximaal 25 calls tegelijkertijd uitvoeren. Hierop is een burst van toepassing. Dit houdt in dat als de 25e bereikt is, je gewoon calls mag blijven sturen. 100 requests bovenop de 25 worden geaccepteerd, maar verwerkt met een snelheid van maximaal 25 tegelijk. Kom je boven de 100 calls die in de wachtrij staan dan krijg je een 429 error. Bovenop de 100 mogen er 400 tegelijkertijd ingeschoten worden. Deze worden wel geaccepteerd, maar verwerkt met een snelheid van maximaal 100 tegelijk.


Ophalen van Checkpoint informatie

Naast het ophalen van informatie over je verzendingen is het mogelijk om de informatie van checkpoints in je campagne op te halen via het checkpoints endpoint. 

Endpoint: https://api.canopydeploy.net/analytics-events/checkpoints?filter[date_from]={{date_from}}&filter[date_to]={{date_to}}

Response Events API 
{
    "total_count": 1,
    "_links": {
        "current": "https://api.deployteq.net/analytics-events/checkpoints?filter%5Bcustomer_id%5D=1&filter%5Bdate_from%5D=2019-01-01&filter%5Bdate_to%5D=2019-01-02&limit=1&offset=0"
    },
    "data": [
        {
            "brand_id": 1,
            "campaign_id": 1,
            "checkpoint_name": "test",
            "checkpoint_value": 1,
            "customer_id": 1,
            "portal_id": 1,
            "timestamp": "2019-01-01T00:00:00+01:00",
            "uuid": "417ddc5d-e556-4d27-95dd-a34d84e46a50"
        }
    ]
}

Checkpoint parameters

Om je resultaten beter te specificieren heb je toegang tot de volgende parameters:

ParamVerplichtToelichting
filter[date_from]Ja

De startdatum van de checkpoint activiteit die je wil ophalen uit de API, met een maximum tot 1 jaar in het verleden.

Formaat: YYYY-mm-dd 

filter[date_to]Ja

De einddatum van de checkpoint activiteit die je wil ophalen uit de API.

Formaat: YYYY-mm-dd 

filter[checkpoint_name]NeeDe naam van een checkpoint zoals ingevoerd in het campagne object.
filter[campaign_id]NeeHet ID van de campagne waar checkpoints in geplaatst zijn.
filter[customer_id]NeeHet ID van CRM records welke door checkpoints gegaan zijn.
filter[uuid]NeeHet GUID van de checkpoint trigger.

Checkpoint data velden

In het checkpoints endpoint krijg je de volgende data velden in de response terug:

VeldnaamToelichtingVoorbeeldwaarde
brand_idNumerieke waarde van het brand_id waarvoor de events worden opgehaald. Deze waarde is uniek per portal.1
campaign_idUnieke ID van de campagne waar het checkpoint in staat.1
checkpoint_nameDe naam van het checkpoint.Succes
customer_idIndien van toepassing, het ID van de customer die het checkpoint triggerde.1
portal_idUnieke identificatie van de portal.1
timestampDe datum- en tijd van dat de metric is geregistreerd; YYYY-mm-ddTHH:mm:ss+Tijdzone.2024-03-04T00:00:00+01:00
uuidUnieke GUID voor het triggeren van het checkpoint.417ddc5d-e556-4d27-95dd-a34d84e46a50