Moeilijkheidsgraad: expert
Inhoud
Leerdoelen
Na het lezen van dit artikel kun je:
- Deep links instellen van een app van derden naar de Workplace-app
Het is mogelijk om de Workplace-app te starten en in één gebruikersactie naar specifieke schermen/functies te navigeren.
Dit gedrag kan worden bereikt door de URL te starten vanuit een webapplicatie/website of vanuit een andere app op hetzelfde apparaat.
Het koppelingsmechanisme wordt ondersteund in de standaard Workplace-app, op zowel iOS- als Android-platforms.
Wat zijn deep links?
Deep links zijn vooraf gedefinieerde aangepaste URL's die kunnen worden gebruikt om een app vanuit een externe app of omgeving aan te roepen. Als je bijvoorbeeld de knop ‘navigeren’ op een website selecteert, wordt de standaardapp ‘kaarten’ op het apparaat gestart en begint de navigatie automatisch.
Vereisten
Om een applicatie te activeren die deep links ondersteunt, moet aan de volgende voorwaarden worden voldaan:
- De doelapp (in dit geval: de Workplace-app) moet op het apparaat zijn geïnstalleerd
- De bronapp moet de aangepaste URL aanroepen om navigatie te activeren
- De URL van de deep link moet correct zijn opgemaakt en alle vereiste parameters bevatten, zoals verwacht door de doelapp.
Deep links in de Workplace-app
De Workplace-app ondersteunt deep links naar de volgende schermen of functies:
- Een ruimte boeken
- De live plattegrond bekijken
Indeling voor het maken van deep links
De deep link bestaat uit 3 secties:
- Schema – De URL die door een app wordt geregistreerd. Hiermee wordt het systeem geïnformeerd dat de app links kan verwerken die met dit schema beginnen.
- Host – Een unieke identificatie voor de app/functie die je wilt aanroepen. Dit is bruikbaar als meerdere pagina's in een app hetzelfde schema verwerken.
- Parameters – Een lijst met sleutel-waardeparen die door de applicatie kunnen worden vastgelegd. Zowel sleutels als waarden moeten van het type tekenreeks zijn.
De indeling waarin deze worden gestructureerd is:
PA://spacewell?targetview={0}&extraparam={1}&username={2}
Waarbij:
Schema = PA://
Host = spacewell
Parameters = targetview, extraparam en username
Host en schema
Voor nu moeten zowel de host als het schema constant blijven bij het maken van deep links voor integratie met de Workplace-app. De verwachte waarden staan hierboven beschreven.
De Workplace-app is zo ontworpen dat deze het schema zowel in hoofdletters als kleine letters kan verwerken, omdat het hoofdlettergevoelig is.
Info
Zorg ervoor dat je hoofdletters en kleine letters niet door elkaar gebruikt in het schema.
Toegestaan
PA://…. OF pa://….
Niet toegestaan
Pa://…. OF pA://….
Parameters
De volgende parameters worden verwacht door de Workplace-app om de bovenstaande gebruiksscenario's mogelijk te maken.
| Sleutel | Doel | Vereist | Details |
|---|---|---|---|
| targetview | Het doelscherm dat via de deep link moet worden gestart. | Moet een van de 5 vooraf gedefinieerde waarden zijn, zoals beschreven in het volgende hoofdstuk. | |
| extraparam | Voor het doorgeven van een aanvullende ID/waarde op basis van targetview | Optioneel | De toegestane combinaties van targetview en extraparam worden beschreven in het volgende hoofdstuk. |
| username |
Workplace-gebruikersnaam of e-mailadres van de gebruiker. Voor een niet-geverifieerde gebruiker is gebruikersidentificatie vereist in de Workplace-app: de aanmeldingsflow wordt geactiveerd. Voor een aangemelde gebruiker, om ervoor te zorgen dat dezelfde gebruiker is geverifieerd in zowel de Workplace-app als de bronapp. Als een e-mailadres wordt gebruikt, moet hetzelfde e-mailadres voor de Workplace-gebruiker zijn geconfigureerd. |
Niet |
Wanneer de gebruikersnaam als parameter wordt doorgegeven: Voor een niet-geverifieerde gebruiker legt de Workplace-app de waarde vast en vult deze in op het gebruikersnaamscherm. De app detecteert automatisch of SSO voor de gebruiker is ingeschakeld en activeert de relevante verificatieflow. In dit geval is het niet mogelijk om met een andere gebruiker in te loggen. Voor een aangemelde gebruiker legt de Workplace-app de gebruikersnaam vast en zorgt deze ervoor dat dezelfde gebruiker is aangemeld. Als dat niet het geval is, wordt de huidige gebruikerssessie beëindigd en wordt de aanmeldingsflow gestart voor de gebruiker die in de link is vastgelegd. Wanneer de gebruikersnaam niet als parameter wordt doorgegeven: Als er geen waarde vanuit de bronapp wordt doorgegeven, worden de gebruikersvergelijkingen in de Workplace-app overgeslagen. Voor een niet-geverifieerde gebruiker moet de Workplace-gebruikersnaam handmatig worden ingevoerd in de Workplace-app als eerste stap. Elke Workplace-gebruiker mag inloggen. Een geverifieerde gebruiker met een actieve Workplace-sessie in de Workplace-app kan daarentegen de app blijven gebruiken wanneer deze ook vanuit een deep link navigeert. Er worden geen gebruikersvergelijkingen uitgevoerd. |
combinaties van targetview en extraparam
De onderstaande combinaties van targetview en extraparam worden ondersteund door de Workplace-app. Als een onjuiste waarde voor targetview wordt doorgegeven, toont de Workplace-app een relevante foutmelding en navigeert deze terug naar de launcher-app. Terugnavigatie wordt standaard alleen op Android ondersteund.
| targetview | extraparam | Beschrijving |
|---|---|---|
| BOOK_ROOM | Niet vereist | Navigeert naar het scherm ‘Een ruimte boeken’, waar de gebruiker kan beginnen met zoeken naar een ruimte. |
| FLOORPLAN | Optioneel |
Om naar een live plattegrondweergave te navigeren. Met extraparam: De verdieping-ID (volgens de gegevens die zijn ontvangen van de Workplace-API's, zie REST API) moet als parameter worden doorgegeven om de gewenste live plattegrond te starten zonder expliciet een verdieping te selecteren. De verdieping moet zich in het huidige gebouw bevinden dat in de Workplace-app is geselecteerd. Zonder extraparam: Wanneer deze link voor de eerste keer wordt gebruikt, wordt de gebruiker gevraagd een verdieping te selecteren uit de beschikbare verdiepingen in het huidige gebouw. Bij volgende starts wordt de eerder geselecteerde verdieping onthouden en wordt de live plattegrond standaard weergegeven. De gebruiker kan nog steeds tussen de verdiepingen in hetzelfde gebouw wisselen. De vorige selectie wordt in de volgende scenario's gewist:
|
Voorbeelden
Het scherm ‘Een ruimte boeken’ starten
structuur: "PA://spacewell?targetview={0}&extraparam={1}&username={2}"
{0} - “BOOK_ROOM”
{1} – “”
{2} - “” OF Workplace-gebruikersnaam/e-mailadres
→ voorbeeld: “PA://spacewell?targetview=BOOK_ROOM”
Probeer het zelf:
Het scherm ‘Plattegrond’ starten
structuur "PA://spacewell?targetview={0}&extraparam={1}&username={2}"
{0} - “FLOORPLAN”
{1} – “” OF locatie-ID van de verdieping die je in de plattegrondweergave wilt openen
{2} - “” OF Workplace-gebruikersnaam/e-mailadres
→ algemeen voorbeeld, waarbij de weergave ‘Alle verdiepingen’ wordt geopend als er meerdere plattegronden beschikbaar zijn in een gebouw: “PA://spacewell?targetview=FLOORPLAN”
→ concreet voorbeeld, waarbij de verdieping-ID wordt gebruikt om één bepaalde verdieping in onze eigen Spacewell-tenant te openen: “PA://spacewell?targetview=FLOORPLAN&extraparam=910000000004545”
Probeer het zelf:
Hoe activeer je de Workplace-app (doelapp) via een link in een bronapp?
Een deep link kan worden beschouwd als hetzelfde als een web-URL, wat betekent dat deze net als elke andere web-URL kan worden gestart. Deze kan worden geactiveerd door op een knop te klikken, in de webbrowser van het apparaat (Chrome/Safari) te worden geplakt of vanuit een native iOS- of Android-app te worden geactiveerd.
Hieronder worden enkele voorbeelden gedeeld die kunnen helpen bij het implementeren van de logica in de bronapps.
Xamarin iOS-voorbeeld
string url = string.Format("PA://spacewell?targetview={0}&extraparam={1}&username={2}", viewName, extraParamValue, userName);
UIApplication.SharedApplication.OpenUrl(new NSUrl(url));
Xamarin Android-voorbeeld
string url = string.Format("PA://spacewell?targetview={0}&extraparam={1}&username={2}", viewName, extraParamValue, userName);
Android.Net.Uri uri = Android.Net.Uri.Parse(url);
Intent intent = new Intent(Intent.ActionView, uri);
StartActivity(intent);
Web/JavaScript
Paginaomleidingen gebruiken
window.location.replace("PA://spacewell?targetview=FLOORPLAN&extraparam=0000012345&username=aaa");
Een link gebruiken
<a href="PA://spacewell?targetview=FLOORPLAN&extraparam=0000012345&username=aaa">Plattegrond</a>
Hoe navigeer je terug naar de bronapp?
Android
Terugnavigatie wordt standaard ondersteund op Android. Wanneer een gebruiker terug navigeert vanuit de Workplace-app en de app vanuit een deep link is aangeroepen, wordt de Workplace-app gesloten en kan de gebruiker verder werken in de vorige app.
Dit biedt de gebruiker een naadloze navigatie-ervaring.
iOS
Op het iOS-platform wordt de launcher-app automatisch naar de achtergrond verplaatst wanneer een app wordt gestart (in dit geval de Workplace-app). Terugnavigatie naar de vorige app is vervolgens niet standaard beschikbaar.
Als terugnavigatie vereist is, kan hetzelfde deep-linkingmechanisme worden gebruikt, maar dan in de tegenovergestelde richting. Hiervoor start de Workplace-app de bronapp (iOS-app) via een deep link die in de bronapp is gedefinieerd.
Om deze functie mogelijk te maken, is waarschijnlijk ontwikkeling in de bron-iOS-app vereist, zodat de Workplace-app terugnavigatie kan activeren met behulp van het onderstaande URL-schema.
“pabacknavigation”
Dit kan worden bereikt door de volgende wijzigingen in de bron-iOS-app te implementeren:
- Implementeer in de AppDelegate de methode OpenURL en retourneer true.
- Voeg in info.plist een aangepast URL-schema toe. Dit moet “pabacknavigation” worden genoemd
Als terugnavigatie niet nodig is, moet de gebruiker na het uitvoeren van een bewerking in de Workplace-iOS-app handmatig terugschakelen naar de bronapp.