Att integrera ditt API med OptiSigns har många användningsområden och möjliggör enkel visning av automatiskt uppdaterad data på dina skärmar. I den här guiden går vi igenom hur du ansluter ditt API - ingen bakgrund inom mjukvaruutveckling krävs.
- Vad API-integration kan göra
- Vad du behöver för att komma igång
-
Hur du konfigurerar en API-förfrågan
- Hur du mappar API-data i Designer
- Mer om OptiSync-användningsområden
|
OBS: API-integration är endast tillgänglig med en Pro Plus-plan eller högre. |
Vad API-integration kan göra
OptiSigns möjliggör enkel integration med användar-API:er. Detta gör att data från en användares API kan visas på någon av dina digitala skyltar. Detta möjliggör dynamiska uppdateringar för:
- Digitala menytavlor - Integrera med dina kassasystem och få menytavlan automatiskt uppdaterad, och redigera formatet på din menytavla med hjälp av Designer-appen när det behövs.
- Automatiserade HR-uppdateringar - Använd API:et från dina HR-system för att automatiskt visa födelsedagar eller arbetsjubileum på skärmarna.
- Lagerinventering - Använd ditt lagers API för att visa lagernivåer med automatiska uppdateringar i hela din organisation
- Alla andra informationsvisningsfall där du behöver konsumera API-data och visa datan på skärmarna.
Denna API-integration kan uppnås i OptiSigns med lite eller ingen kodning, vilket gör det tillgängligt för de utan bakgrund inom mjukvaruutveckling. I den här guiden går vi igenom hur du konfigurerar det med exemplet nedan med hjälp av ett API från Clover POS-systemet.
Vad du behöver för att komma igång
Du behöver din:
- API-slutpunkts-URL
- API-auktoriseringstoken
Dessa krävs för att OptiSigns ska kunna ansluta till ditt önskade API. Se till att du har dem lätt tillgängliga innan du försöker konfigurera din API-förfrågan i OptiSigns webbportal. Du bör kunna få dessa från en IT-expert i din organisation eller genom din kassasystemadministratör.
Hur du konfigurerar en API-förfrågan
API-gatewayen är ett kraftfullt verktyg som låter användare centralt hantera API:erna, samt konfigurera och testa API:erna.
Nu när du har allt du behöver, låt oss börja med att konfigurera en API-förfrågan. Med en API-förfrågan kan du:
- Använda OptiSigns API Keystore för att säkert lagra och använda API-nycklar från andra system.
- Testa API-slutpunkterna, med möjlighet att modifiera headers och parametrar.
- Använda substitutionsparametrar och förbehandlings- och efterbehandlingsregler för att hantera komplexa integrationer. Förbehandlingsregler kan hjälpa dig att hantera de API-integrationssituationer som kräver ett ytterligare anrop för att få en autentiseringstoken innan API-anropet görs. Efterbehandling låter dig bearbeta den returnerade datan och anpassa den för att passa ditt användningsområde bättre.
För att komma igång, öppna din OptiSigns webbportal.
När du är där, navigera till det övre högra hörnet av skärmen och hovra över ditt kontonamn.
Hovra över Mer → Datakällor
Du kommer att se skärmen nedan.
Nu är du redo att börja.
Steg 1: Lagra din API-auktoriseringstoken i OptiSigns API Keystore
Det första steget är att ta din API-auktoriseringstoken och lagra den i OptiSigns API Keystore.
Detta steg är tekniskt sett valfritt: du kan mata in din API-auktoriseringstoken i en individuell API-förfrågan. Men Keystore har några stora fördelar:
- Låter din API-auktoriseringstoken skickas till flera API-förfrågningar, utan att behöva mata in den manuellt varje gång
- Ger överlägsen säkerhet för din API-auktoriseringstoken, vilket gör det mycket svårare för utomstående aktörer att upptäcka den
Därför rekommenderar vi starkt detta steg.
För att gå till Keystore, hitta Låsikonen och klicka på den.
Detta öppnar API Keystore.
Klicka på Lägg till nyckel.
Det finns två fält här.
- Första fältet - Ange namnet på nyckeln här. Vi rekommenderar något som hjälper dig att komma ihåg den. Du kommer att använda detta för att konfigurera en API-förfrågan.
- Andra fältet - Den faktiska unika lösenordskoden för din API-kommunikation.
När du har matat in din API-auktoriseringstoken, klicka på Spara. När du vill köra en förfrågan med denna API-nyckel använder du termen: {{apiKeystore.<<key>>}} där "<<key>>" ersätts med namnet du angav tidigare. I detta exempel döper vi vår förfrågan till "clover".
Nu är vi redo att konfigurera din API-förfrågan.
Steg 2: Konfigurera och testa API-förfrågan
Innan du går vidare i OptiSigns rekommenderar vi att testa ditt API-anslutning med ett gratis verktyg, såsom Postman. Detta ger flera fördelar, inklusive:
- Kontrollera din dataformatering
- Säkerställa att rätt data tillhandahålls
- Verifiera din autentisering
- Identifiera integrationsproblem eller anslutningsfel
Testparametrarna, slutpunkterna och autentiseringarna kan sedan användas i OptiSigns för att konfigurera din API-förfrågan. Så här gör du det.
Klicka på knappen Lägg till förfrågan, det öppnar fönstret för dig att konfigurera och testa API-förfrågan.
- Visningsnamn - Detta visas under API-gateway-listan, främst för att hjälpa användare identifiera API-förfrågan.
- Namn - Detta används som en referens till API-förfrågan, det är ett tekniskt namn som kommer att användas senare i sökvägen för att hänvisa till API-förfrågans data.
- URL - Detta är API-slutpunkten, du kan använda GET- eller POST-metoden beroende på API-förfrågan, till exempel, om du använder GraphQL, kommer alla förfrågningar att använda POST.
- Params - Låter dig definiera parametrarna i din API-förfrågan. Du kan se parametrar i din API-slutpunkts-URL, dessa kommer att föregås av ett "?"-tecken. Dessa kan användas i för- och efterbehandlingskod för att ytterligare automatisera din API-förfrågan.
- Headers - Header(s) för API-förfrågan. Här vill du mata in din API-autentiseringstoken.
- Förbehandling - En valfri kodbit som förbereder kontexten före API-förfrågan. Till exempel kan du behöva anropa ett annat API för att få en kortlivad autentiseringstoken innan du anropar API:et, eller du behöver beräkna några variabler som ska användas i API-förfrågan.
- Efterbehandling - En valfri kodbit som modifierar data som tagits emot från förfrågan. Till exempel, om datan du tar emot inte är exakt hur du vill att den ska visas, kan du skriva lite kod för att modifiera den enligt dina digitala skärmbehov.
- Aktivera Webhook - Genererar en webhook-länk och en tillhörande token. Denna webhook kan användas för att meddela oss om en förändring i datan, vilket kommer att uppdatera API-förfrågan och uppdatera dina skärmar automatiskt.
- Aktivera denna förfrågan - Ställ in status för API-förfrågan.
För att testa förfrågan behöver vi konfigurera headern. Det är här Keystore kommer in. I den andra rutan, skriv Bearer {{apiKeystore.<<key>>}}, där Bearer är typen av token och {{apiKeystore.<<key>>}} hämtar token som lagrats i Keystore. I detta exempel använder vi namnet "clover" som refereras ovan.
När det är gjort, klicka på "Kör test". Om svarskoden är 200 har API:et returnerat data framgångsrikt. Om det finns någon annan kod finns det ett problem i API-förfrågan.
Hur du använder parametrar
Parametrar finns i URL:er av alla typer. Det finns två element i en parameter:
- De måste följa ett '?'-tecken i URL:en;
- De har ett värde associerat med dem
Fliken Params låter dig specificera parametrarna vars värde du vill ändra.
Vanligtvis används fliken Params tillsammans med flikarna Förbehandling och Efterbehandling för att skapa automatiskt uppdaterande värden.
Hur du använder för- och efterbehandling
För att använda för- och efterbehandling behövs viss Javascript-kunskap.
| Vad är skillnaden mellan de två? |
| Förbehandling: Detta är en kodsnutt som normalt ställer in kontexten före API-förfrågan. Detta kan vara att hämta en autentiseringstoken från ett annat API, eller att ändra parametrar för att möjliggöra mer automatisering. |
| Efterbehandling: En kodbit att tillämpa på datan mottagen från API-förfrågan. Denna kod kan användas för att modifiera den mottagna datan för att ändra hur den visas på dina skärmar. |
Fliken Förbehandling är där du matar in kod för förbehandling.
Exempel: För system som kräver en dynamiskt genererad autentiseringstoken som Toast, kan detta användas för att anropa ett annat API för att hämta autentiseringstoken och ställa in den i API:ets kontext.
För mer om detta exempel, se denna artikel om hur du ansluter ditt Toast API.
Fliken Efterbehandling är där du matar in kod för efterbehandling.
Exempel: Du tar emot data från ditt kassasystems (POS) API, men vissa delar av datan visas inte som du vill.
Priser kan visas som heltal (dvs. 1299) istället för som korrekt prissättning (dvs. $12.99). För detta skulle vi behöva en kodbit för att konvertera heltalet till ett pris, och låta den koden vara utökningsbar för liknande visningsfel (t.ex. 1899 istället för $18.99).
För detta vanliga exempel bör denna JavaScript-kodbit lösa ditt problem. Vi kan också konfigurera möjligheten att mappa produkttillgänglighet samtidigt.
Detta kommer att fixa den returnerade datan, vilket gör att den visas korrekt:
Detta kan också användas för att få data att visas som "SLUTSÅLD", för att stryka över en artikel om den inte är tillgänglig, eller för att visa varningar i ett lagerhanteringssystem. För mer om detta exempel, se vår artikel om Digitala menytavlor.
Steg 3 (Valfritt): Använd substitutionsparametrar från enhetsattribut.
Många kassasystem (POS) är licensierade per butik/plats. Det är möjligt att konfigurera en enda API-förfrågan med OptiSync och få den att fungera med olika platser med hjälp av substitutionsparametrar. Att mata in dessa låter din skärm kommunicera sin butiks- eller platsidentifieringsinformation. Detta innebär att en enda API-förfrågan kan kommunicera olika data till olika butiker eller platser, snarare än att behöva göra individuella API-förfrågningar per skärm.
För att komma igång, hitta skärmen du vill redigera.
Klicka på Avancerat → Mer → Enhets ytterligare attribut.
Två fält kommer att visas, Nyckel och Värde.
- Nyckel - En parameter som kommer att användas under API-anropet för att ersätta för din butiks värde. Detta kommer att ersätta en del av din API URL-slutpunkt.
- Värde - Representerar den unika koden associerad med butiken eller platsen du vill skicka till ditt API.
I detta exempel underhåller vi Clover merchantID här. Värdet som matas in måste erhållas från din sida eftersom det kommer att vara unikt.
Gå nu tillbaka till API-förfrågans konfigurationssida. Ersätt merchantID i API-slutpunkten med nyckelnamnet du tidigare definierade.
När API-anropet utlöses på enheten kommer det att ta värdet från enheten och ersätta det vid körning. För varje skärm vill du utföra samma steg, behålla nyckelnamnet detsamma medan du ändrar värdet. Detta låter dig skicka olika data till olika skärmar.
Hur du mappar API-data i Designer
För att kunna skicka data från ditt API till en skärm måste den registreras som en datakälla. Detta låter dataelement läggas till OptiSigns Designer-app, där det kan formateras och införlivas i vilken visuell design du vill visa.
Designer-appen och mallarna kan användas för att göra formateringen, och API-datakällan kommer att hantera datamappningen. Alla textrutor eller bildelement kan mappas i Designer. När du mappar ett bildelement kommer bildens URL att ersättas vid körning.
Steg 1: Skapa en API-datakälla
För att komma igång, hitta din design eller skapa en ny i fliken Filer/Tillgångar.
Med designen öppen, klicka på "Datakälla" i vänsterkolumnen. Klicka sedan på "Lägg till datakälla" för att lägga till en API-datakälla till designen.
Scrolla ner till där det står "API Gateway" och klicka på det.
Du bör se denna skärm:
Välj API-förfrågan som skapades ovan. Du kommer att se en skärm som den nedan:
Här kan du välja vilken data specifikt du vill lägga till designen. Om du vill ha alla alternativ, klicka på "Fortsätt". Denna skärm kommer att visas.
Datakällans namn är hur denna datakälla kommer att visas i Designer. Namnge den vad som hjälper dig identifiera den.
Synkronisering låter dig välja hur ofta du ska synkronisera tillbaka till ditt API. Importera bara en gång är vettigt för engångskampanjer och liknande. Om detta är för en långsiktig tillgång, välj Periodisk direktåtkomst eller Periodisk bakgrundssynkronisering beroende på om du behöver använda data från specifik enhet för att ställa in kontexten.
Klicka på Klar, och datakällan skapas.
Den bör visas i vänsterkolumnen under "Används i denna design". Den kommer definitivt att visas i sektionen "Andra datakällor" . Du kan behöva uppdatera sidan för att den ska visas.
Nu går vi vidare till steg 2.
Steg 2: Underhåll elementmappningen
När API-datakällan har skapats är du redo att mappa datan.
I Designer, öppna din datakälla.
Klicka på den och en skärm liknande denna kommer att dyka upp:
Att öppna någon av dessa kommer att visa data som hämtats från ditt API:
Genom att klicka på en del av denna data och dra den till skärmen kommer datan att visas. Du kommer att ha alternativet att använda datan som en Repeater eller för sig själv.
I detta fall vill vi använda den för sig själv. För menyer är en Repeater mest vettig.
För att kontrollera databindningen kan du klicka på vilket mappat element som helst och sedan klicka på Inställningar. Du kommer att se Tillgångselementets namn där.
Vi har artikelnamnet och priset från API:et mappat till designen. När det publiceras på skärmen kommer värdet automatiskt att ersättas med värdet från API:et. Om uppdateringar görs i Clover POS-systemet kommer ändringen att återspeglas på skärmen automatiskt.
Upprepa detta steg för alla element som du vill mappa till API-datakällan och spara designen. Din design är redo att användas.
Mer om OptiSync-användningsområden
Om du vill ha mer information om API-integrationsanvändningsområden har vi flera ytterligare artiklar. Se gärna:
- Kassasystem för att bygga digitala menytavlor
- Visa händelsescheman
- Integrera Toast API-system
- Anpassade RSS-flöden
- Dynamisk datamappning
Det är allt!
Så här integrerar du API-data och får det publicerat på din skärm. Viktigast av allt, utan kodning!
Om du har ytterligare frågor, funderingar eller feedback om OptiSigns, tveka inte att kontakta vårt supportteam på support@optisigns.com