Je activity feed in een IRL-streaming-app: donaties en events teruglezen

Tijdens een IRL-stream heb je andere behoeften dan achter je bureau. Je wilt kort kunnen zien wie heeft gedoneerd, welk bericht erbij hoort en welke andere activiteit je hebt gemist. Een eigen app kan dat precies zo tonen als jij prettig vindt. De DonoLink activity feed API levert de opgeslagen events; je eigen app bepaalt de presentatie en de manier waarop je ze verwerkt.

Een actuele feed is meer dan een lijstje verversen

Als je bij ieder request alleen de nieuwste tien events ophaalt, kun je tijdens een drukke stream of een lange netwerkonderbreking oudere gebeurtenissen overslaan. Voor een doorlopende integratie wil je daarom de feed vanaf een bekend punt doorlopen. Gebruik oplopende volgorde met order=asc en bewaar de cursor die de API teruggeeft.

Stel bij het starten van je integratie een vaste since-grens in. Deze filtert op het moment waarop DonoLink een event opsloeg, niet op de oorspronkelijke datum van een geïmporteerde donatie. Pas de grens tijdens het pollen niet telkens aan naar “nu”: daarmee verander je de query en vervalt je bestaande cursor.

De leeslus voor je IRL-app

1. Vraag maximaal 100 events op met je persoonlijke API key, order=asc en je vaste filters.
2. Verwerk ieder event op basis van zijn unieke ID. Als dat ID al verwerkt is, voer je de bijbehorende actie niet opnieuw uit.
3. Bewaar pagination.next_cursor pas nadat alle events van de pagina succesvol zijn verwerkt.
4. Is has_more waar, lees dan direct de volgende pagina. Anders wacht je ongeveer vijf seconden.
5. Bewaar de filters en cursor in je eigen opslag, zodat je na het herstarten van je app kunt hervatten.

De documentatie bevat een Node.js-voorbeeld met deze lus. Je vult zelf de functies in waarmee je events verwerkt en de cursor bewaart. Een lege pagina betekent dat er voor die query op dat moment geen nieuwe opgeslagen events zijn. Bij een bestaande cursor geeft de API die cursor terug, zodat je vanaf hetzelfde punt kunt blijven kijken.

Wat doe je bij slecht bereik?

Een netwerkfout is geen reden om je cursor te wissen. Laat je app tijdelijk een verbindingsstatus tonen, wacht en probeer dezelfde aanvraag opnieuw. Bij HTTP 429 of 503 geeft DonoLink Retry-After: 60 terug. Respecteer die wachttijd. Bij een verlopen of ingetrokken sleutel krijg je 401; dan is een nieuwe sleutel nodig in plaats van eindeloos opnieuw proberen.

De feed is geen gegarandeerde exactly-once eventbus. Een betaling kan later worden terugbetaald of betwist, en opgeslagen records kunnen verdwijnen. Maak je verwerking daarom bestand tegen herhaling. Voor herstel kun je een overlappende periode opnieuw lezen en bekende event-ID’s overslaan. Gebruik de feed niet om automatische betalingen of andere onomkeerbare acties aan te sturen.

Kies welke informatie onderweg relevant is

Met type=donation beperk je de feed tot donaties. Met platform=donolink selecteer je DonoLink-donaties; geïmporteerde donaties hebben hun eigen bron. Laat de filters weg als je ook opgeslagen follows, subscriptions, gifted subs, cheers en raids wilt zien. De eventvelden en eenheden staan in de eventreferentie.

Houd je mobiele interface rustig: bijvoorbeeld de schermnaam, het bericht en de waarde van het laatste event. Toon geldbedragen als valuta en centen; toon TikTok-diamonds als diamonds. Schermnamen en berichten zijn invoer van derden, dus render ze als gewone tekst. Een bericht mag nooit HTML of code in je app worden.

Bewaar je API key buiten je streambeeld

Voer in een persoonlijke native app je eigen sleutel in en bewaar hem in Keychain of Android Keystore. Zet nooit één gedeelde sleutel in een app die je aan anderen verspreidt. Bouw je voor meerdere streamers, dan heeft ieder account eigen geheimen en eigen gegevens nodig. API v1 heeft nog geen OAuth-flow waarmee andere gebruikers jouw app toestemming kunnen geven.

Begin met de introductie tot de DonoLink Developer API en maak daarna je sleutel onder Instellingen → Developer. Heb je vooral een donatielink voor je stream nodig? Dan kun je eerst een gratis account maken en je donatiepagina instellen, zonder zelf een app te bouwen.