Een dashboardtool met Bird API's

E-mail

·

24 mrt 2022

Een dashboardtool met Bird API's

Belangrijkste punten

    • Bird APIs kunnen worden gecombineerd met Python en Plotly Dash om krachtige, interactieve dashboards te bouwen zonder de volledige Bird UI nodig te hebben.

    • Het project demonstreert hoe men metrieken en evenementen kan visualiseren met behulp van Bird’s Metrics API en Events API binnen een aangepaste webapplicatie.

    • Plotly Dash biedt een snelle, open-source framework voor het bouwen van UI-elementen zoals dropdowns, grafieken en tabellen.

    • Ontwikkelaars kunnen de tool uitbreiden met leverbaarheidsanalyse, filtering en paginering voor rijkere dashboards.

    • Toekomstige verbeteringen omvatten caching, verbeterde UI en integratie met andere Bird-producten of externe APIs.

    • De codebase (beschikbaar op GitHub) biedt een sterk startpunt voor iedereen die Bird-gestuurde dashboards of klantgerichte portalen wil bouwen.

Q&A Hoogtepunten

  • Wat is het doel van dit dashboardproject?

    Het toont hoe ontwikkelaars Bird APIs kunnen gebruiken met Python en Plotly Dash om data-gedreven dashboards te creëren die campagnemetingen en recente evenementen visualiseren.

  • Waarom Plotly Dash gebruiken voor Bird APIs?

    Dash is open source, gemakkelijk aan te passen, en ideaal voor het maken van interactieve gebruikersinterfaces zonder dat voorkennis van front-end nodig is.

  • Wat toont het dashboard?

    Het visualiseert tijdreeksmetingen van Bird’s Metrics API en recente gebeurtenisgegevens van de Events API, met opties om metingen over aangepaste tijdsintervallen te filteren en selecteren.

  • Hoe kan de tool verder worden uitgebreid?

    Door bezorgingsanalyses, geavanceerde filters, gegevenscaching en paginering voor grote datasets toe te voegen om de prestaties en bruikbaarheid te verbeteren.

  • Welke vaardigheden of tools zijn vereist om het te runnen?

    Basiskennis van Python en installatie van requests, dash en pandas. Een API-sleutel van Bird is vereist om gegevens op te halen.

  • Hoe past dit project in Bird’s ecosysteem?

    Het illustreert hoe Bird’s open API's kunnen worden benut om aangepaste dashboards en rapportagetools te creëren voor teams of klanten zonder toegang tot het volledige platform.

Dit script raakt slechts de oppervlakte van wat mogelijk is met behulp van Python, Plotly Dash en onze API's.

Bird Metrics API + Dashboarding met Python

Bijna een jaar geleden schreef Tom Mairs, Bird's directeur klantensucces, een mailertool die Bird API's gebruikt. In deze post ga ik verder waar hij stopte. Zijn tool maakt tijdgestuurde verzending van taken mogelijk, maar wat als we onze eigen dashboards en gebeurtenislogboeken willen maken?

Misschien wil ik een specifiek dashboard maken voor een zakelijke groep of een klantgericht dashboard, maar niet gebruikers volledige toegang tot de Bird UI geven. Dit script raakt slechts de oppervlakte van wat mogelijk is met Python, Plotly Dash, en onze API's. Bij het bouwen van dashboards die API-data van hoge volumes verwerken, moet men zich bewust zijn dat infrastructuurcomponenten zoals DNS knelpunten kunnen worden - we hebben AWS DNS schaaluitdagingen ervaren die onze dataverwerkingscapaciteiten beïnvloedden. Voor liefhebbers van visuele workflows, kun je ook Flow Builder met Google Cloud Functions en Vision API integreren onderzoeken om AI-gestuurde automatisering aan je dataverwerkingspipelijnen toe te voegen.

Toen ik mijn zoektocht online begon, wilde ik het pad van de minste weerstand vinden. Ik had alle dashboards en UI zelf kunnen maken in HTML en Python, maar na wat Google-zoekopdrachten kwam ik Plotly’s Dash tegen, dat gemakkelijk met Python integreert. Ik koos Dash om 2 redenen: 1) het is open source, en 2) na het lezen van de documentatie leek het gemakkelijk aanpasbaar voor wat ik probeerde te doen. Dash is een open-source bibliotheek die ideaal is voor het bouwen en implementeren van data-apps met aangepaste gebruikersinterfaces. Dit maakte het maken van een UI extreem eenvoudig. De vraag werd toen, hoe complex wilde ik deze app maken? Hoe meer tijd ik besteedde, hoe meer functies ik wilde toevoegen.

Voor het initiële project wilde ik ervoor zorgen dat ik een dashboard had met aanpasbare statistieken en een selecteerbare tijdsperiode. Aanvankelijk begon ik met een dashboard waar je slechts één statistiek uit het dropdown-menu kon kiezen. Toen ik feedback van collega's kreeg, verfijnde ik het dashboard een beetje om multi-select en as-titels toe te voegen. Ik besloot ook een extra tabblad toe te voegen voor een gebeurtenislogboek. Ik kwam op het punt dat ik tevreden was met wat ik had als een goed startpunt voor iedereen die zijn eigen dashboards wilde bouwen. Voor ontwikkelaars die realtime webhook-data in hun dashboards willen invoeren, bekijk onze gids over webhook-consumenten bouwen met Azure Functions. Natuurlijk heb ik het project op Github gezet voor je om te klonen of te vertakken.

Aan de slag

Om toegang te krijgen tot deze app, moet je ervoor zorgen dat je python 3.10 of hoger gebruikt en de volgende bibliotheken installeert:

Python Library

Doel

requests

API-communicatie met Bird diensten

dash

UI en dashboardweergave

pandas

Dataverwerking en tabelgeneratie

Voer vervolgens je API-sleutel in App.py in en start de app. Het zal draaien op http://localhost:8050. Voor meer informatie over het implementeren naar een openbaar toegankelijke server (zoals AWS), zie de volgende bronnen:

Het creëren van de Dashboard Pagina

Eerst initialiseer je het data frame en het dashboard. Zonder het dashboard te initialiseren, verschijnt er geen dashboard in de UI.

df = pd.DataFrame({
    "Count": [0, 0],
    "Time": [0, 0]
})
fig = px.line(df, x="Time", y="Count")

Vervolgens bouw je de eerste tab. Dit is een combinatie van een app callback (om te controleren welke tab wordt gebruikt) samen met een conditionele functie om te controleren welke tab momenteel is geselecteerd. De onderstaande code bouwt alleen het lege dashboard en de UI-elementen uit (we komen later op het gebeurtenistabblad terug). De dcc-elementen zijn de Dash Core Components en de HTML Components maken het gemakkelijk om HTML in de UI te gebruiken.

html.H2("Analytics Dashboard"),
# Multi-select dropdown
dcc.Dropdown(
    [
        "Count Accepted",
        "Count Admin Bounce",
        "Count Block Bounce",
        "Count Bounce",
        "Count Clicked",
        "Count Delayed",
        "Count Delayed First",
        "Count Delivered",
        "Count Delivered First",
        "Count Delivered Subsequent",
        "Count Generation Failed",
        "Count Generation Rejection",
        "Count Hard Bounce",
        "Count Inband Bounce",
        "Count Initial Rendered",
        "Count Injected",
        "Count Out of Band Bounce",
        "Count Policy Rejection",
        "Count Rejected",
        "Count Rendered",
        "Count Sent",
        "Count Soft Bounce",
        "Count Spam Complaint",
        "Count Targeted",
        "Count Undetermined Bounce",
        "Count Unique Clicked",
        "Count Unique Confirmed Opened",
        "Count Unique Initial Rendered",
        "Count Unique Rendered",
        "Count Unsubscribe",
        "Total Delivery Time First",
        "Total Delivery Time Subsequent",
        "Total Message Volume",
    ],
    id="y-axis",
    multi=True,
    searchable=True,
    placeholder="Select metrics(s)",
),
# Date selector (max date allowed is set to today's date)
dcc.DatePickerRange(
    id="date-picker-range",
    start_date=date(2022, 1, 1),
    end_date=date(2022, 2, 1),
    max_date_allowed=date(
        datetime.today().year,
        datetime.today().month,
        datetime.today().day,
    ),
),
# Graph object
dcc.Graph(id="Emails", figure=fig)

Let op hoe eenvoudig het is om een dashboard-UI te maken met een multi-select, doorzoekbare dropdown in dash. Om multi-select of zoeken uit te schakelen, kunnen de parameters voor het maken van een dropdown eenvoudig worden aangepast. Ik vond dat het meest complexe deel van dit project het bouwen van het eigenlijke data frame uit invoer was, evenals het correct laten werken van de HTML + CSS in de UI.

De Time Series Metrics API maakt het mogelijk om 33 individuele metrics op te halen op basis van een datum/tijdsbereik. Je kunt dieper filteren op Domeinen, Campagnes, IP Pools, Verstuurdomeinen, Subaccounts en de Precisie van tijdreeksen specificeren. Deze extra filters samen met leveringsanalyses kunnen in de toekomst verbeterd worden voor dit project (foutafhandeling moet worden geïmplementeerd voor klanten die geen toegang hebben tot leveringsanalyses).

Door gebruik te maken van en aan te roepen de Metrics API, bouw ik een dashboard met de door de gebruiker geselecteerde parameters en gespecificeerde tijdsbestek. Het geïnitialiseerde dashboard wordt vervolgens geüpdatet.

Dashboardweergave (Time Series Metrics API)

# Build the API call utilizing the parameters provided
params = {
    "from": start_date + "T00:00",
    "to": end_date + "T00:00",
    "delimiter": ",",
    "precision": "day",
    "metrics": joined_values
}
api_url = BASE_URL + "/metrics/deliverability/time-series"
response_API = requests.get(api_url, headers={"Authorization": API_KEY}, params=params)
response_info = json.loads(response_API.text)
new_df = pd.json_normalize(response_info, record_path=['results'])
value_array = joined_values.split(",")
# Build out a new dashboard utilizing the new metrics and dates from the updated API call
fig = px.line(
    new_df,
    x=new_df['ts'],
    y=value_array,
    labels={"value": "Count", "variable": "Metric", "ts": "Date"}
)
fig.update_xaxes(title_text="Time")
fig.update_yaxes(title_text="Count")
return fig

Het volgende is een voorbeeld van meerdere geselecteerde metrics en een uitgebreid tijdsbestek.


Sparkpost analytics dashboard

Opmerking: er zijn veel dingen automatisch ingebouwd in de dash-grafiek (hover, zoom, auto-schalen).

Eerst initialiseer je het data frame en het dashboard. Zonder het dashboard te initialiseren, verschijnt er geen dashboard in de UI.

df = pd.DataFrame({
    "Count": [0, 0],
    "Time": [0, 0]
})
fig = px.line(df, x="Time", y="Count")

Vervolgens bouw je de eerste tab. Dit is een combinatie van een app callback (om te controleren welke tab wordt gebruikt) samen met een conditionele functie om te controleren welke tab momenteel is geselecteerd. De onderstaande code bouwt alleen het lege dashboard en de UI-elementen uit (we komen later op het gebeurtenistabblad terug). De dcc-elementen zijn de Dash Core Components en de HTML Components maken het gemakkelijk om HTML in de UI te gebruiken.

html.H2("Analytics Dashboard"),
# Multi-select dropdown
dcc.Dropdown(
    [
        "Count Accepted",
        "Count Admin Bounce",
        "Count Block Bounce",
        "Count Bounce",
        "Count Clicked",
        "Count Delayed",
        "Count Delayed First",
        "Count Delivered",
        "Count Delivered First",
        "Count Delivered Subsequent",
        "Count Generation Failed",
        "Count Generation Rejection",
        "Count Hard Bounce",
        "Count Inband Bounce",
        "Count Initial Rendered",
        "Count Injected",
        "Count Out of Band Bounce",
        "Count Policy Rejection",
        "Count Rejected",
        "Count Rendered",
        "Count Sent",
        "Count Soft Bounce",
        "Count Spam Complaint",
        "Count Targeted",
        "Count Undetermined Bounce",
        "Count Unique Clicked",
        "Count Unique Confirmed Opened",
        "Count Unique Initial Rendered",
        "Count Unique Rendered",
        "Count Unsubscribe",
        "Total Delivery Time First",
        "Total Delivery Time Subsequent",
        "Total Message Volume",
    ],
    id="y-axis",
    multi=True,
    searchable=True,
    placeholder="Select metrics(s)",
),
# Date selector (max date allowed is set to today's date)
dcc.DatePickerRange(
    id="date-picker-range",
    start_date=date(2022, 1, 1),
    end_date=date(2022, 2, 1),
    max_date_allowed=date(
        datetime.today().year,
        datetime.today().month,
        datetime.today().day,
    ),
),
# Graph object
dcc.Graph(id="Emails", figure=fig)

Let op hoe eenvoudig het is om een dashboard-UI te maken met een multi-select, doorzoekbare dropdown in dash. Om multi-select of zoeken uit te schakelen, kunnen de parameters voor het maken van een dropdown eenvoudig worden aangepast. Ik vond dat het meest complexe deel van dit project het bouwen van het eigenlijke data frame uit invoer was, evenals het correct laten werken van de HTML + CSS in de UI.

De Time Series Metrics API maakt het mogelijk om 33 individuele metrics op te halen op basis van een datum/tijdsbereik. Je kunt dieper filteren op Domeinen, Campagnes, IP Pools, Verstuurdomeinen, Subaccounts en de Precisie van tijdreeksen specificeren. Deze extra filters samen met leveringsanalyses kunnen in de toekomst verbeterd worden voor dit project (foutafhandeling moet worden geïmplementeerd voor klanten die geen toegang hebben tot leveringsanalyses).

Door gebruik te maken van en aan te roepen de Metrics API, bouw ik een dashboard met de door de gebruiker geselecteerde parameters en gespecificeerde tijdsbestek. Het geïnitialiseerde dashboard wordt vervolgens geüpdatet.

Dashboardweergave (Time Series Metrics API)

# Build the API call utilizing the parameters provided
params = {
    "from": start_date + "T00:00",
    "to": end_date + "T00:00",
    "delimiter": ",",
    "precision": "day",
    "metrics": joined_values
}
api_url = BASE_URL + "/metrics/deliverability/time-series"
response_API = requests.get(api_url, headers={"Authorization": API_KEY}, params=params)
response_info = json.loads(response_API.text)
new_df = pd.json_normalize(response_info, record_path=['results'])
value_array = joined_values.split(",")
# Build out a new dashboard utilizing the new metrics and dates from the updated API call
fig = px.line(
    new_df,
    x=new_df['ts'],
    y=value_array,
    labels={"value": "Count", "variable": "Metric", "ts": "Date"}
)
fig.update_xaxes(title_text="Time")
fig.update_yaxes(title_text="Count")
return fig

Het volgende is een voorbeeld van meerdere geselecteerde metrics en een uitgebreid tijdsbestek.


Sparkpost analytics dashboard

Opmerking: er zijn veel dingen automatisch ingebouwd in de dash-grafiek (hover, zoom, auto-schalen).

Eerst initialiseer je het data frame en het dashboard. Zonder het dashboard te initialiseren, verschijnt er geen dashboard in de UI.

df = pd.DataFrame({
    "Count": [0, 0],
    "Time": [0, 0]
})
fig = px.line(df, x="Time", y="Count")

Vervolgens bouw je de eerste tab. Dit is een combinatie van een app callback (om te controleren welke tab wordt gebruikt) samen met een conditionele functie om te controleren welke tab momenteel is geselecteerd. De onderstaande code bouwt alleen het lege dashboard en de UI-elementen uit (we komen later op het gebeurtenistabblad terug). De dcc-elementen zijn de Dash Core Components en de HTML Components maken het gemakkelijk om HTML in de UI te gebruiken.

html.H2("Analytics Dashboard"),
# Multi-select dropdown
dcc.Dropdown(
    [
        "Count Accepted",
        "Count Admin Bounce",
        "Count Block Bounce",
        "Count Bounce",
        "Count Clicked",
        "Count Delayed",
        "Count Delayed First",
        "Count Delivered",
        "Count Delivered First",
        "Count Delivered Subsequent",
        "Count Generation Failed",
        "Count Generation Rejection",
        "Count Hard Bounce",
        "Count Inband Bounce",
        "Count Initial Rendered",
        "Count Injected",
        "Count Out of Band Bounce",
        "Count Policy Rejection",
        "Count Rejected",
        "Count Rendered",
        "Count Sent",
        "Count Soft Bounce",
        "Count Spam Complaint",
        "Count Targeted",
        "Count Undetermined Bounce",
        "Count Unique Clicked",
        "Count Unique Confirmed Opened",
        "Count Unique Initial Rendered",
        "Count Unique Rendered",
        "Count Unsubscribe",
        "Total Delivery Time First",
        "Total Delivery Time Subsequent",
        "Total Message Volume",
    ],
    id="y-axis",
    multi=True,
    searchable=True,
    placeholder="Select metrics(s)",
),
# Date selector (max date allowed is set to today's date)
dcc.DatePickerRange(
    id="date-picker-range",
    start_date=date(2022, 1, 1),
    end_date=date(2022, 2, 1),
    max_date_allowed=date(
        datetime.today().year,
        datetime.today().month,
        datetime.today().day,
    ),
),
# Graph object
dcc.Graph(id="Emails", figure=fig)

Let op hoe eenvoudig het is om een dashboard-UI te maken met een multi-select, doorzoekbare dropdown in dash. Om multi-select of zoeken uit te schakelen, kunnen de parameters voor het maken van een dropdown eenvoudig worden aangepast. Ik vond dat het meest complexe deel van dit project het bouwen van het eigenlijke data frame uit invoer was, evenals het correct laten werken van de HTML + CSS in de UI.

De Time Series Metrics API maakt het mogelijk om 33 individuele metrics op te halen op basis van een datum/tijdsbereik. Je kunt dieper filteren op Domeinen, Campagnes, IP Pools, Verstuurdomeinen, Subaccounts en de Precisie van tijdreeksen specificeren. Deze extra filters samen met leveringsanalyses kunnen in de toekomst verbeterd worden voor dit project (foutafhandeling moet worden geïmplementeerd voor klanten die geen toegang hebben tot leveringsanalyses).

Door gebruik te maken van en aan te roepen de Metrics API, bouw ik een dashboard met de door de gebruiker geselecteerde parameters en gespecificeerde tijdsbestek. Het geïnitialiseerde dashboard wordt vervolgens geüpdatet.

Dashboardweergave (Time Series Metrics API)

# Build the API call utilizing the parameters provided
params = {
    "from": start_date + "T00:00",
    "to": end_date + "T00:00",
    "delimiter": ",",
    "precision": "day",
    "metrics": joined_values
}
api_url = BASE_URL + "/metrics/deliverability/time-series"
response_API = requests.get(api_url, headers={"Authorization": API_KEY}, params=params)
response_info = json.loads(response_API.text)
new_df = pd.json_normalize(response_info, record_path=['results'])
value_array = joined_values.split(",")
# Build out a new dashboard utilizing the new metrics and dates from the updated API call
fig = px.line(
    new_df,
    x=new_df['ts'],
    y=value_array,
    labels={"value": "Count", "variable": "Metric", "ts": "Date"}
)
fig.update_xaxes(title_text="Time")
fig.update_yaxes(title_text="Count")
return fig

Het volgende is een voorbeeld van meerdere geselecteerde metrics en een uitgebreid tijdsbestek.


Sparkpost analytics dashboard

Opmerking: er zijn veel dingen automatisch ingebouwd in de dash-grafiek (hover, zoom, auto-schalen).

De Event Details Page maken

De evenementendetailpagina was iets moeilijker omdat ik niet wist hoe ik alle evenement-metrieken op de best leesbare manier kon presenteren. Ik overwoog om filterparameters aan deze pagina toe te voegen, maar besloot dat dit een aanzienlijke hoeveelheid tijd aan dit project zou toevoegen, aangezien de tabel dan dynamisch zou moeten zijn (samen met het toevoegen van de parameters, callbacks, enz.). Ik koos ervoor om alle evenementen te tonen en de timestamp eerst te plaatsen (want zonder de timestamp eerst te plaatsen, was de{

Volgende Stappen

Voor iemand die zijn eigen dashboard of gebeurtenissenlogboek wil maken, is dit een goed begin. Met de aanpasbaarheid hier is de lucht de limiet.

Zoals hierboven besproken, zijn enkele toekomstige verbeteringen die kunnen worden gemaakt:

  • Toevoegen van bezorganalyse aan het dashboard

  • Meer filters toevoegen aan het dashboard

  • Mogelijke caching-opties zodat de API niet elke keer wordt aangeroepen om de pagina's weer te geven

  • UI-verbeteringen

  • Filtering en paginering toevoegen aan de gebeurtenisdetailpagina

Ik zou geïnteresseerd zijn in het horen van feedback of suggesties om dit project uit te breiden.

~ Zach Samuels, Bird Senior Solutions Engineer

Overig nieuws

Lees meer uit deze categorie

A person is standing at a desk while typing on a laptop.

Het complete AI-native platform dat met uw bedrijf meegroeit.

A person is standing at a desk while typing on a laptop.

Het complete AI-native platform dat met uw bedrijf meegroeit.