Het integreren van uw API met OptiSigns heeft veel toepassingen en maakt het eenvoudig om automatisch bijgewerkte gegevens op uw schermen weer te geven. In deze handleiding laten we u zien hoe u uw API kunt verbinden - geen software engineering achtergrond vereist.
- Wat API-integratie kan doen
- Wat u nodig heeft om te beginnen
-
Hoe u een API-verzoek instelt
- Hoe API-gegevens in Designer te mappen
- Meer over OptiSync use cases
|
OPMERKING: API-integratie is alleen beschikbaar met een Pro Plus abonnement of hoger. |
Wat API-integratie kan doen
OptiSigns maakt eenvoudige integratie met gebruikers-API's mogelijk. Hierdoor kunnen gegevens van de API van een gebruiker op al uw digitale schermen worden weergegeven. Dit maakt dynamische updates mogelijk voor:
- Digitale menuborden - Integreer met uw POS-systemen en laat het DMB automatisch bijwerken, en bewerk het formaat van uw DMB met behulp van de designer app wanneer nodig.
- Geautomatiseerde HR-updates - Gebruik de API van uw HR-systemen om automatisch verjaardagen of werkjubilea op de schermen weer te geven.
- Magazijnvoorraad bijhouden - Gebruik de API van uw magazijn om voorraadniveaus weer te geven met automatische updates in uw hele organisatie
- Alle andere use cases voor informatieweergave waarbij u API-gegevens moet consumeren en de gegevens op de schermen moet weergeven.
Deze API-integratie kan in OptiSigns worden gerealiseerd met weinig tot geen codering, waardoor het toegankelijk is voor mensen zonder achtergrond in software engineering. In deze handleiding laten we u zien hoe u het instelt met het onderstaande voorbeeld met behulp van een API van het Clover POS-systeem.
Wat u nodig heeft om te beginnen
U heeft het volgende nodig:
- API Endpoint URL
- API Autorisatietoken
Deze zijn vereist om OptiSigns te laten verbinden met uw gewenste API. Zorg ervoor dat u deze op een gemakkelijk toegankelijke plaats heeft voordat u probeert uw API-verzoek in het OptiSigns webportaal in te stellen. U zou deze moeten kunnen verkrijgen van een IT-professional in uw organisatie, of via uw POS-systeembeheerder.
Hoe u een API-verzoek instelt
De API-gateway is een krachtig hulpmiddel waarmee gebruikers de API's centraal kunnen beheren, evenals de API's kunnen configureren en testen.
Nu u alles heeft wat u nodig heeft, laten we beginnen met het instellen van een API-verzoek. Met een API-verzoek kunt u:
- De OptiSigns API Keystore gebruiken om API-sleutels van andere systemen veilig op te slaan en te gebruiken.
- De API-eindpunten testen, met de mogelijkheid om headers en parameters aan te passen.
- Substitutieparameters en pre- en post-verwerkingsregels gebruiken om complexe integratie af te handelen. Pre-verwerkingsregels kunnen u helpen bij het afhandelen van API-integratiesituaties die een extra aanroep vereisen om een authenticatietoken te krijgen voordat de API-aanroep wordt gedaan. Post-verwerking stelt u in staat om de geretourneerde gegevens te verwerken en aan te passen aan uw gebruik.
Om te beginnen, opent u uw OptiSigns webportaal.
Navigeer naar de rechterbovenhoek van het scherm en beweeg over uw accountnaam.
Beweeg over Meer → DataSources
U ziet het onderstaande scherm.
Nu bent u klaar om te beginnen.
Stap 1: Sla uw API-autorisatietoken op in de OptiSigns API Keystore
De eerste stap is om uw API-autorisatietoken te nemen en deze op te slaan in de OptiSigns API Keystore.
Deze stap is technisch gezien optioneel: u kunt uw API-autorisatietoken in een individueel API-verzoek invoeren. De Keystore heeft echter een paar grote voordelen:
- Maakt het mogelijk om uw API-autorisatietoken naar meerdere API-verzoeken te sturen, zonder deze elke keer handmatig in te voeren
- Biedt superieure beveiliging voor uw API-autorisatietoken, waardoor het veel moeilijker wordt voor externe partijen om deze te ontdekken
Daarom bevelen we deze stap sterk aan.
Om de Keystore te openen, zoekt u het slotpictogram en klikt u erop.
Dit opent de API Keystore.
Klik op Sleutel toevoegen.
Er zijn hier twee velden.
- Eerste veld - Voer hier de naam van de sleutel in. We raden iets aan dat u helpt deze te onthouden. U gebruikt dit om een API-verzoek in te stellen.
- Tweede veld - De werkelijke unieke toegangscode voor uw API-communicatie.
Nadat u uw API-autorisatietoken heeft ingevoerd, klikt u op Opslaan. Wanneer u een verzoek wilt uitvoeren met deze API-sleutel, gebruikt u de term: {{apiKeystore.<<key>>}} waarbij "<<key>>" wordt vervangen door de naam die u eerder heeft ingevoerd. In dit voorbeeld noemen we ons verzoek "clover".
Nu zijn we klaar om uw API-verzoek in te stellen.
Stap 2: Stel het API-verzoek in en test het
Voordat u verder gaat in OptiSigns, raden we aan om uw API te testen met behulp van een gratis tool, zoals Postman. Dit biedt verschillende voordelen, waaronder:
- Uw gegevensformattering controleren
- Ervoor zorgen dat de juiste gegevens worden verstrekt
- Uw authenticatie verifiëren
- Integratieproblemen of verbindingsfouten identificeren
De testparameters, eindpunten en authenticators kunnen vervolgens in OptiSigns worden gebruikt om uw API-verzoek in te stellen. Hier leest u hoe u dat doet.
Klik op de knop Verzoek toevoegen, het opent het venster voor u om het API-verzoek te configureren en te testen.
- Weergavenaam - Dit wordt weergegeven onder de API-gatewaylijst, voornamelijk om gebruikers te helpen het API-verzoek te identificeren.
- Naam - Dit wordt gebruikt als referentie naar het API-verzoek, het is een technische naam die later in het pad wordt gebruikt om te verwijzen naar de API-verzoekgegevens.
- URL - Dit is het API-eindpunt, u kunt de GET- of POST-methode gebruiken, afhankelijk van het API-verzoek, bijvoorbeeld als u GraphQL gebruikt, dan gebruiken alle verzoeken POST.
- Params - Hiermee kunt u de parameters in uw API-verzoek definiëren. U ziet mogelijk parameters in uw API-eindpunt-URL, deze worden voorafgegaan door een "?"-teken. Deze kunnen worden gebruikt in pre- en post-verwerkingsverzoekcode om uw API-verzoek verder te automatiseren.
- Headers - De header(s) van het API-verzoek. U wilt hier uw API-authenticatietoken invoeren.
- Pre-request - Een optioneel stukje code dat de context voorbereidt vóór het API-verzoek. U moet bijvoorbeeld een andere API aanroepen om een kortdurend authenticatietoken te krijgen voordat u de API aanroept, of u moet enkele variabelen berekenen die in het API-verzoek moeten worden gebruikt.
- Post-request - Een optioneel stukje code dat de gegevens wijzigt die van het verzoek zijn ontvangen. Als de gegevens die u ontvangt bijvoorbeeld niet precies zijn zoals u ze wilt weergeven, kunt u een beetje code schrijven om deze aan te passen aan uw digitale weergavebehoeften.
- Webhook inschakelen - Genereert een webhook-link en een bijbehorend token. Deze webhook kan worden gebruikt om ons op de hoogte te stellen van een wijziging in de gegevens, waardoor het API-verzoek wordt vernieuwd en uw schermen automatisch worden bijgewerkt.
- Dit verzoek inschakelen - Stel de status van het API-verzoek in.
Om het verzoek te testen, moeten we de header configureren. Hier komt de Keystore van pas. Typ in het tweede vak Bearer {{apiKeystore.<<key>>}}, waarbij Bearer het type token is en {{apiKeystore.<<key>>}} het token ophaalt dat is opgeslagen in de Keystore. In dit voorbeeld gebruiken we de naam "clover" zoals hierboven vermeld.
Als dat is gebeurd, klikt u op "Test uitvoeren". Als de responscode 200 is, heeft de API met succes gegevens geretourneerd. Als er een andere code is, is er een probleem in het API-verzoek.
Hoe parameters te gebruiken
Parameters zijn aanwezig in URL's van alle typen. Er zijn twee elementen in een parameter:
- Ze moeten een '?'-teken in de URL volgen;
- Er is een waarde aan gekoppeld
Met het tabblad Params kunt u de parameters opgeven waarvan u de waarde wilt wijzigen.
Gewoonlijk wordt het tabblad Params gebruikt in combinatie met de tabbladen Pre-request en Post-request om automatisch bijwerkende waarden te creëren.
Hoe pre- en post-request verwerking te gebruiken
Om pre- en post-request verwerking te gebruiken, is enige kennis van Javascript nodig.
| Wat is het verschil tussen de twee? |
| Pre-request: Dit is een codefragment dat normaal gesproken de context instelt vóór het API-verzoek. Dit kan het ophalen van een authenticatietoken van een andere API zijn, of het wijzigen van parameters voor meer automatisering. |
| Post-request: Een stukje code om toe te passen op de gegevens ontvangen van het API-verzoek. Deze code kan worden gebruikt om de ontvangen gegevens te wijzigen om te veranderen hoe deze op uw schermen worden weergegeven. |
Het tabblad Pre-request is waar u code invoert voor pre-request verwerking.
Voorbeeld: Voor systemen die een dynamisch gegenereerd authenticatietoken vereisen zoals Toast, kan dit worden gebruikt om een andere API aan te roepen om het authenticatietoken op te halen en in te stellen in de context van de API.
Voor meer over dit voorbeeld, zie dit artikel over hoe u uw Toast API verbindt.
Het tabblad Post-request is waar u code invoert voor post-request verwerking.
Voorbeeld: U ontvangt gegevens van uw point-of-sale (POS) software API, maar bepaalde gegevens worden niet weergegeven zoals u zou willen.
Prijzen kunnen worden weergegeven als hele getallen (bijv. 1299) in plaats van als een juiste prijs (bijv. €12,99). Hiervoor hebben we een stukje code nodig om het hele getal om te zetten in een prijs, en ervoor te zorgen dat die code uitbreidbaar is voor soortgelijke weergavefouten (bijv. 1899 in plaats van €18,99).
Voor dit veel voorkomende voorbeeld zou dit stukje JavaScript-code uw probleem moeten oplossen. We kunnen tegelijkertijd ook de mogelijkheid instellen om productbeschikbaarheid te mappen.
Dit zal de geretourneerde gegevens corrigeren, zodat ze correct worden weergegeven:
Dit kan ook worden gebruikt om gegevens te laten verschijnen als "UITVERKOCHT", om een item door te strepen als het niet beschikbaar is, of om waarschuwingen weer te geven in een voorraadbeheersysteem. Voor meer over dit voorbeeld, zie ons artikel over Digitale menuborden.
Stap 3 (Optioneel): Gebruik substitutieparameters van apparaatattributen.
Veel point-of-sale (POS) systemen hebben licenties per winkel/locatie. Het is mogelijk om een enkel API-verzoek met OptiSync te configureren en het te laten werken met verschillende locaties met behulp van substitutieparameters. Door deze in te voeren kan uw scherm zijn winkel- of locatie-identificatiegegevens communiceren. Dit betekent dat een enkel API-verzoek verschillende gegevens naar verschillende winkels of locaties kan communiceren, in plaats van individuele API-verzoeken per scherm te moeten maken.
Om te beginnen, zoekt u het scherm dat u wilt bewerken.
Klik op Geavanceerd → Meer → Extra apparaatattributen.
Er verschijnen twee velden, Sleutel en Waarde.
- Sleutel - Een parameter die wordt gebruikt tijdens de API-aanroep om te vervangen door de waarde van uw winkel. Dit vervangt een deel van uw API URL-eindpunt.
- Waarde - Vertegenwoordigt de unieke code die is gekoppeld aan de winkel of locatie die u wilt doorgeven aan uw API.
In dit voorbeeld behouden we hier de Clover merchantID. De ingevoerde waarde moet aan uw kant worden verkregen omdat deze uniek is.
Ga nu terug naar de API-verzoek configuratiepagina. Vervang de merchantID in het API-eindpunt door de sleutelnaam die u eerder heeft gedefinieerd.
Wanneer de API-aanroep op het apparaat wordt geactiveerd, neemt het de waarde van het apparaat en vervangt deze tijdens runtime. Voor elk scherm wilt u dezelfde stappen uitvoeren, waarbij u de sleutelnaam hetzelfde houdt terwijl u de waarde wijzigt. Hierdoor kunt u verschillende gegevens naar verschillende schermen pushen.
Hoe API-gegevens in Designer te mappen
Om gegevens van uw API naar een scherm te pushen, moet het worden geregistreerd als een DataSource. Hierdoor kunnen gegevenselementen worden toegevoegd aan de Designer-app van OptiSigns, waar het kan worden geformatteerd en opgenomen in elk visueel ontwerp dat u wilt weergeven.
De Designer-app en sjablonen kunnen worden gebruikt voor de opmaak, en de API-gegevensbron zal de gegevensmapping afhandelen. Elk tekstvak of afbeeldingselement kan worden gemapped in Designer. Wanneer u een afbeeldingselement mapt, wordt de URL van de afbeelding tijdens runtime vervangen.
Stap 1: Een API DataSource aanmaken
Om te beginnen, zoekt u uw ontwerp of maakt u een nieuwe aan in het tabblad Bestanden/Assets.
Met het ontwerp geopend, klikt u op "DataSource" in de linkerkolom. Klik vervolgens op "DataSource toevoegen" om een API-gegevensbron aan het ontwerp toe te voegen.
Scroll naar beneden naar waar "API Gateway" staat en klik erop.
U zou dit scherm moeten zien:
Selecteer het hierboven gemaakte API-verzoek. U ziet een scherm zoals het onderstaande:
Hier kunt u kiezen welke gegevens u specifiek wilt toevoegen aan het ontwerp. Als u alle opties wilt, klikt u op "Doorgaan". Dit scherm verschijnt.
DataSource naam is hoe deze DataSource in Designer zal verschijnen. Noem het wat u helpt het te identificeren.
Synchronisatie laat u kiezen hoe vaak u wilt synchroniseren met uw API. Slechts één keer importeren is logisch voor eenmalige promoties en dergelijke. Als dit voor een langetermijnasset is, kies dan Periodieke directe toegang of Periodieke achtergrondsynchronisatie afhankelijk van of u de gegevens van een specifiek apparaat moet gebruiken om de context in te stellen.
Klik op Klaar, en de DataSource is aangemaakt.
Het zou in de linkerkolom moeten verschijnen onder "Gebruikt in dit ontwerp". Het zal zeker verschijnen in de sectie "Andere DataSources". Mogelijk moet u de pagina vernieuwen om het te laten verschijnen.
Nu gaan we naar stap 2.
Stap 2: De elementtoewijzing onderhouden
Zodra de API DataSource is aangemaakt, bent u klaar om de gegevens te mappen.
Open uw DataSource in Designer.
Klik erop en een scherm vergelijkbaar met dit zal verschijnen:
Als u een van deze opent, worden de gegevens weergegeven die uit uw API zijn opgehaald:
Door op een stuk van deze gegevens te klikken en het naar het scherm te slepen, verschijnen de gegevens. U heeft de optie om de gegevens als een Repeater of op zichzelf te gebruiken.
In dit geval willen we het op zichzelf gebruiken. Voor menu's is een Repeater het meest logisch.
Om de gegevensbinding te controleren, kunt u op elk gemapped element klikken en vervolgens op Instellingen klikken. U ziet de Asset Element Name daar.
We hebben de itemnaam en prijs van de API gekoppeld aan het ontwerp. Wanneer gepubliceerd op het scherm, wordt de waarde automatisch vervangen door de waarde van de API. Als er updates worden gemaakt in het Clover POS-systeem, wordt de wijziging automatisch op het scherm weergegeven.
Herhaal deze stap voor alle elementen die u wilt koppelen aan de API-gegevensbron en sla het ontwerp op. Uw ontwerp is klaar voor gebruik.
Meer OptiSync use cases
Als u meer details wilt over API-integratie use cases, hebben we verschillende aanvullende artikelen. Zie:
- Point-of-Sale systemen om digitale menuborden te bouwen
- Evenementenschema's weergeven
- Toast API-systemen integreren
- Aangepaste RSS-feeds
- Dynamische gegevensmapping
Dat is alles!
Dit is hoe u API-gegevens integreert en ze publiceert op uw scherm. Het belangrijkste is, zonder codering!
Als u aanvullende vragen, opmerkingen of feedback over OptiSigns heeft, neem dan gerust contact op met ons ondersteuningsteam via support@optisigns.com