Deep linking naar de Workplace App
- Lango: Language and translation manager
- Sergio Karijodinomo
Moeilijkheidsgraad: expert
Leerdoelen
Na het lezen van dit artikel zul je in staat zijn om:
Deep links instellen van app van derden naar Workplace app
Het is mogelijk om Workplace App te starten en met één enkele 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 op de standaard Workplace app, zowel op iOS als Android platformen.
Wat zijn deep links?
Deep links zijn vooraf gedefinieerde aangepaste URL's die kunnen worden gebruikt om een app aan te roepen vanuit een externe app of omgeving. Als je bijvoorbeeld de knop "navigeren" selecteert op een website, wordt de standaardapplicatie "kaarten" gestart op het apparaat, waar de navigatie automatisch wordt gestart.
Vereisten
Om een toepassing te activeren die deeplinks ondersteunt, moet aan de volgende voorwaarden worden voldaan:
De app van bestemming (in dit geval: The Workplace App) moet geïnstalleerd zijn op het apparaat
De bron-app moet de aangepaste URL aanroepen om navigatie te activeren
De deep link URL moet goed geformatteerd zijn en alle vereiste parameters doorgeven, zoals verwacht door de bestemmingsapp.
Deep links in de Workplace app
De Workplace app ondersteunt deeplinks naar de onderstaande schermen of functies:
Boek een kamer
Bekijk live plattegrond
Bouwformaat met diepe verbinding
De deeplink bestaat uit 3 delen:
Regeling - De URL die is geregistreerd door een app. Hiermee wordt het systeem geïnformeerd dat de app links kan verwerken die beginnen met dit schema.
Gastheer - Een unieke identificatie voor de app/functie die je wilt aanroepen. Dit is bruikbaar als meerdere pagina's in een app hetzelfde schema afhandelen.
Parameters - Een lijst van key-value paren, die kunnen worden vastgelegd door de applicatie. Zowel de sleutels als de waarden moeten van het type string zijn.
Het formaat waarin deze zijn gestructureerd is:
PA://spacewell?targetview={0}&extraparam={1}&username={2}
Waar,
Regeling = PA://
Gastheer = spacewell
Parameters = targetview, extraparam en gebruikersnaam
Gastheer en regeling
Voorlopig moeten zowel host als schema constant blijven tijdens het maken van deeplinks voor integratie met de Workplace app. De verwachte waarden zijn hierboven beschreven.
De Workplace app is zo ontworpen dat het zowel hoofdletters als kleine letters kan verwerken, omdat het hoofdlettergevoelig is.
Zorg ervoor dat je geen hoofdletters en kleine letters 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 use cases mogelijk te maken.
Sleutel | Doel | Vereist | Details |
doelweergave | Het doelscherm dat moet worden gestart via de deeplink. | Ja | Moet een van de voorgedefinieerde 5 waarden zijn, zoals beschreven in het volgende hoofdstuk. |
extraparam | Voor het doorgeven van extra ID/waarde gebaseerd op targetview | Optioneel | De toegestane combinaties van targetview en extraparam worden beschreven in het volgende hoofdstuk. |
gebruikersnaam | Workplace gebruikersnaam of e-mailadres van de gebruiker.
Voor een niet-geauthenticeerde gebruiker is gebruikersidentificatie vereist in de Workplace app: start de aanmeldingsstroom.
Voor een ingelogde gebruiker, om ervoor te zorgen dat dezelfde gebruiker wordt geverifieerd in de Workplace app en de bron app.
Als een e-mail-ID wordt gebruikt, moet dezelfde e-mail-ID worden geconfigureerd voor de Workplace-gebruiker. | Geen | Wanneer de gebruikersnaam als parameter wordt doorgegeven: Voor een ongeauthenticeerde gebruikerDe Workplace app vangt de waarde op en vult deze in op het gebruikersnaamscherm. Er wordt automatisch gedetecteerd of SSO is ingeschakeld voor de gebruiker en de relevante verificatiestroom wordt geactiveerd. In dit geval is het niet mogelijk om in te loggen met een andere gebruiker.
Voor een ingelogde gebruikerDe Workplace app zal de gebruikersnaam vastleggen en controleren of dezelfde gebruiker is ingelogd. Als dat niet het geval is, wordt de huidige gebruikerssessie beëindigd en wordt de aanmeldingsstroom geactiveerd voor de gebruiker die is vastgelegd in de koppeling.
Als de gebruikersnaam niet als parameter wordt doorgegeven: Als er geen waarde wordt doorgegeven vanuit de bron-app, worden de gebruikersvergelijkingen overgeslagen in de Workplace app.
Voor een niet-geauthenticeerde gebruiker moet de Workplace gebruikersnaam als eerste stap handmatig worden ingevoerd in de Workplace app. Elke Workplace gebruiker mag inloggen.
Aan de andere kant kan een geverifieerde gebruiker met een actieve Workplace sessie in de Workplace app de app ook blijven gebruiken wanneer hij vanuit een deeplink navigeert. Er worden geen gebruikersvergelijkingen gemaakt. |
targetview en extraparam combinaties
De onderstaande combinaties van targetview en extraparam worden ondersteund door de Workplace app. Als een onjuiste waarde wordt doorgegeven voor targetview, zal de Workplace app een relevante foutmelding tonen en terugnavigeren naar de launcher app. Terugnavigatie wordt alleen op Android out of the box ondersteund.
doelweergave | extraparam | Beschrijving |
BOEKENKAMER | Niet vereist | Navigeert naar het scherm "Boek een kamer" waar de gebruiker kan beginnen met het zoeken naar een kamer. |
PLATTEGROND | Optioneel | Om naar een live plattegrondweergave te gaan.
Met extraparam: De vloer-ID (volgens gegevens ontvangen van Workplace API's, zie Rest API) moet worden doorgegeven als parameter om de gewenste live plattegrond te starten zonder expliciete vloerkeuze. De verdieping moet zich binnen het huidige gebouw bevinden dat is geselecteerd in de Workplace app.
Zonder extraparam: Bij het eerste gebruik van deze link wordt de gebruiker gevraagd een verdieping te selecteren uit de beschikbare verdiepingen in het huidige gebouw. Bij volgende lanceringen wordt de eerder geselecteerde verdieping onthouden en wordt standaard de live plattegrond getoond. De gebruiker heeft nog steeds de mogelijkheid om te wisselen tussen de verdiepingen in hetzelfde gebouw.
In de onderstaande scenario's wordt de vorige selectie gewist:
|
Voorbeelden
Start het scherm "Boek een kamer
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:
Start het scherm "Plattegrond
structuur "PA://spacewell?targetview={0}&extraparam={1}&username={2}"
{0} - "PLATTEGROND"
{1} - OF locatie-ID van de verdieping die u wilt openen in plattegrondweergave
{2} - "" OF Workplace gebruikersnaam/ e-mailadres
→ algemeen voorbeeld, het openen van de weergave "Alle verdiepingen" als er meerdere plattegronden beschikbaar zijn in een gebouw: "PA://spacewell?targetview=FLOORPLAN".
→ concreet voorbeeld, vloer-ID gebruiken om 1 bepaalde verdieping in onze eigen Spacewell-huurder te openen: "PA://spacewell?targetview=FLOORPLAN&extraparam=910000000004545".
Probeer het zelf:
Hoe kan ik een Workplace app (bestemmingsapp) activeren vanuit een link in een bronapp?
Een deeplink kan worden beschouwd als hetzelfde als een web URL, wat betekent dat het kan worden gelanceerd zoals elke andere web URL. De link kan worden gebruikt door op een knop te klikken, kan worden geplakt in de webbrowser van het apparaat (Chrome/Safari) of kan worden gebruikt vanuit een native iOS- of Android-app.
Hieronder staan enkele voorbeelden die kunnen helpen bij het implementeren van de logica in de bron-apps.
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 = nieuwe Intent(Intent.ActionView, uri);
StartActiviteit(intentie);
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">Vloerplan</a>
Hoe navigeer ik terug naar de bronapp?
Android
Terugnavigatie in Android wordt out-of-the-box ondersteund. Wanneer een gebruiker terugnavigeert vanuit de Workplace app en de app werd aangeroepen vanuit een deeplink, wordt de Workplace app verlaten en kan de gebruiker verder werken in de vorige app.
Dit biedt de gebruiker een naadloze navigatie-ervaring.
iOS
Op het iOS-platform wordt bij het starten van een app (in dit geval de Workplace-app) de launcher-app automatisch naar de achtergrond verplaatst. Vervolgens is terugnavigeren naar de vorige app niet direct beschikbaar.
Als terugnavigatie vereist is, kan hetzelfde deep linking mechanisme worden gebruikt, maar dan in omgekeerde richting. Om dit mogelijk te maken, zal de Workplace app de bron app (iOS app) starten via een deep link die is gedefinieerd in de bron app.
Om deze functie in te schakelen, is waarschijnlijk een ontwikkeling nodig in de iOS app als bron; de Workplace app kan de terug-navigatie activeren met behulp van het onderstaande URL-schema.
"pabacknavigation"
Dit kan worden bereikt door de onderstaande wijzigingen door te voeren in de iOS app als broncode:
Implementeer in de AppDelegate de methode OpenURL en retourneer true.
Voeg in info.plist een aangepast URL-schema toe. Het moet "pabacknavigation" heten.
Als terugnavigatie niet nodig is, moet de gebruiker handmatig terugschakelen naar de bron-app na het uitvoeren van een bewerking in de Workplace iOS app.
Zoek op