Ihre Vorteile
In diesem Tutorial erklären wir Ihnen, wie Sie Ihre erste Experience App mit einer Kombination von Showpad-Entwicklerwerkzeugen erstellen können. Dies setzt mittlere Kenntnisse in Showpad und Frontend-Entwicklung voraus. Wenn Sie neu in der Entwicklung sind, empfehlen wir Ihnen, einen Blick auf die Übersicht der von uns bereitgestellten Entwicklerwerkzeuge zu werfen.
Wir werden eine Experience App mit folgenden Offline-Funktionen erstellen:
- Abfrage von Assets nach Tags
- Hinzufügen von Assets zu einer Sammlung
- Assets teilen
- Assets hochladen
Sie finden einige Hinweise, in denen wir Tipps, Tricks und Fakten für fortgeschrittene Entwickler erklären. Sie können dies im Tutorial ohne Bedenken überspringen. Am Ende dieser Seite finden Sie Vorher- und Nachher-ZIP-Dateien, die Ihnen den Start- und Endzustand des Projekts zeigen.
Hinweis: Die aktuelle Windows-App verwendet IE11 als Render-Engine. Unsere App wird nicht funktionieren, da unsere Syntax ES6-gestützt ist.
Was Sie für den Erfolg benötigen
- Admin-Zugriff auf eine Showpad-Domäne
- Assets mit Tags, die für die Suche verwendet werden
- Showpad Ultimate-Lizenz
- NodeJs zur Installation unseres SDK
- Installlation des Showpad-SDK
- OAuth-Client
- Authentifizierung
- Manifest.json
- Config.json
- Index.html
- SDK-Entwicklungsserver
- window.onShowpadLibLoaded
- Übersetzungen
- ShowpadLib.getAssetsByTags
- ShowpadLib.getAssetPreviewUrl
- ShowpadLib.addAssetsToCollection & ShowpadLib.share
- ShowpadLib.upload & ShowpadLib.displayToast
- Stellen wir unsere App fertig
- Schlussnotiz
Ihre Schritt-für-Schritt-Anleitung
Wir haben eine ZIP-Datei mit unserer Ordnerstruktur und einigen Dateien vorbereitet. Laden Sie diese vorgefertigte ZIP-Datei für die Experience App herunter und extrahieren Sie sie in einen lokalen Ordner auf Ihrem System.
Sie können das SDK mithilfe des folgenden Befehls installieren:
npm i @showpad/sdk -g
Sie benötigen einen OAuth-Client, um sich und unsere Anwendung zu authentifizieren.
- Gehen Sie zum Showpad-Backend und klicken Sie auf das Zahnrad und auf Integrationen.
- Klicken Sie auf OAuth-Clients verwalten und dann auf den Plus-Button, um einen neuen Client zu erstellen. Verwenden Sie die folgenden Parameter für Ihren OAuth-Client:
- Name: Entwickler-Client
- URL-Weiterleitung: https://yourdomain.showpad.biz
- Beschreibung: OAuth-Client zur Entwicklung von Experience-Apps
- Website: https://yourdomain.showpad.biz
- Dieser Client muss: aktivieren Sie alle Kontrollkästchen
Nun haben wir unseren OAuth-Client, müssen unseren Benutzer aber noch für diesen Client authentifizieren.
- Ändern Sie die fett gedruckten Parameter dieser URL und fügen Sie sie in einen Browser-Tab ein. https://yourdomain.showpad.biz/api/v2/oauth2/authorize?client_id=clientid&redirect_uri=https://yourdomain.showpad.biz&response_type=code
- Akzeptieren Sie die Anfrage und Ihr aktuell angemeldeter Benutzer wird für diesen Client authentifiziert.
Wir werden das SDK verwenden, um unsere Authentifizierungsdatei zu erstellen.
- Gehen Sie in Ihrem Kommandozeilen-Tool zu unserem Verzeichnis und verwenden Sie den folgenden Befehl.
Showpad auth
- Ihnen werden einige Fragen gestellt. Ihr Showpad-Benutzername ist Ihre E-Mail-Adresse. Im Verzeichnis sollte sich eine neue .showpadconfig.json-Datei befinden.
Die Datei manifest.json enthält allgemeine Informationen über Ihre Experience-App. Stellen Sie sicher, dass Ihr Identifikator für jede Experience App, die Sie erstellen, eindeutig ist, und erhöhen Sie die Versionsnummer jedes Mal, wenn Sie eine neue Version in Showpad hochladen. Kopieren Sie die folgende Struktur und fügen Sie sie in die Datei src/m anifest.json ein. Sie können Ihren Namen als Autor angeben.
{
"identifier": "com.org.showpad.my.first.experience.app",
"name": "Meine erste Experience App",
"version": "0.0.1",
"description": "Tutorial zum Erstellen einer Experience App",
"author": "Showpad"
}
Die Datei config.json bestimmt die Struktur der Labels und Inhalte, die vom Showpad-Admin geändert werden können.
- Labels können Einstellungen oder Übersetzungen sein und sind textbasiert.
- Die Assets, auf die Ihre App und der zugeordnete Benutzer Zugriff haben sollen, werden durch die Inhalte definiert. Die Assets sind offline verfügbar. Stellen Sie sicher, dass die Datei config.json keine Objektschlüssel wie type, value etc. enthält, die von Showpad reserviert sein könnten. Befinden sich die Objetschlüssel in der folgenden Liste, können sie nicht als benutzerdefinierte Schlüssel verwendet werden: https://showpad.pages.showpad.io/public-sdk/config.json.html.
Wir werden den Labels einige Übersetzungen hinzufügen und Assets mit Tags anfordern, nach denen wir später suchen können. Kopieren Sie die folgende Struktur und fügen Sie sie in src/c onfig.json ein. Setzen Sie ["tag1", "tag2", "tag3"] auf die Tags, die Sie tatsächlich im Backend verwenden. Stellen Sie sicher, dass Assets mit den von Ihnen eingegebenen Tags existieren.
{
"version": 1,
"labels": {
"translations": {
"title": {
"value": "Tutorial",
"description": "Title"
},
"search_button": {
"value": "Search",
"description": "Search button"
},
"add_to_collection_button": {
"value": "Add to collection",
"description": "Add to collection button"
},
"share_button": {
"value": "Share",
"description": "Share button"
},
"upload_button": {
"value": "Upload",
"description": "Upload button"
}
}
},
"contents": {
"assets": {
"search": {
"type": "tags",
"value": { "or": [ "tag1", "tag2", "tag3" ] },
"description": "Searchable assets"
}
}
}
}
Die index.html ist der Einstiegspunkt in unsere Experience App. Hier können Sie Ihre Struktur einrichten und alle notwendigen Ressourcen wie css und js hinzufügen. Die Vorlage enthält bereits unsere Struktur. Jetzt, da alles vorbereitet ist, können wir mit der Entwicklung unserer App beginnen.
Für die Entwicklung von Experience Apps. Wir werden den SDK-Entwicklungsserver verwenden. Dadurch wird die ShowpadLib in unsere Anwendung eingefügt und das Verhalten unserer App in einem Iframe nachgebildet, was auch auf der Plattform der Fall sein wird.
- Um den Server zu starten, geben Sie Folgendes in Ihr Kommandozeilen-Tool ein (im Stammverzeichnis).
showpad experience serve
- Eine neue Registerkarte mit der folgenden URL wird geöffnet: http://localhost:9000/. Sie sehen bereits einige gestaltete Elemente, da wir CSS in unsere index.html geladen haben.
Hinweis: Wenn Sie mithilfe eines Frameworks wie React entwickeln möchten, können Sie Ihren Entwicklungsserver über einen anderen Port (z.B. 8080) starten und den Showpad-Server darauf verweisen. Stellen Sie sicher, dass Ihr Public Path relativ ist.
showpad experience serve --host http://localhost:8080
Wir wollen wissen, wann Showpad unsere Anwendung geladen hat. Wenn wir versuchen, ShowpadLib-Methoden vorher aufzurufen, schlagen sie fehl.
- Als nächstes wollen wir unsere Konfiguration aus der config.json-Datei laden, um auf unsere Labels, Inhalte und Assets zuzugreifen. Das Asset-Objekt enthält die Assets, die Sie im Inhalt definiert haben. Diese Assets enthalten alle notwendigen Informationen für die ShowpadLib-Methoden, die wir verwenden werden.
- Sobald die Konfiguration geladen ist, werden wir diese Objekte im Fenster platzieren, damit wir in der gesamten App problemlos darauf zugreifen können. Kopieren Sie den folgenden Code und fügen Sie ihn in src/js/app.js ein.
function init () {
console.log(window.labels)
console.log(window.contents)
console.log(window.assets)
}
window.onShowpadLibLoaded = () => {
window.ShowpadLib.getShowpadApi((apiConfig) => {
let url = window.location.href.split('configUrl=')[1].split('&')[0]
url = decodeURIComponent(url)
fetch(url, {
method: 'GET',
headers: {
'Authorization': 'Bearer ' + apiConfig.accessToken,
'Content-Type': 'application/json; charset=utf-8'
}
})
.then(function (response) {
return response.json()
})
.then(function (data) {
window.labels = data.labels
window.contents = data.contents
window.assets = data.assets
init()
})
})
}
Sie sollten nun Ihre definierten Labels und Inhalte sehen. Im Asset-Objekt sehen wir einige Mock-ID-Informationen. Das ist das SDK, das uns sagt, dass es unsere Assets imitiert.
Hinweis: Während der Entwicklung kann es vorkommen, dass nicht die neuesten Labels und Inhalte geladen werden. Dies kann auf verschiedene Situationen zurückzuführen sein, in denen Sie z.B. bereits eine Version zum Testen hochgeladen haben. Sie können dieses Problem auf zwei Arten lösen. Die erste besteht darin, den Identifikator in Ihrer App zu ändern. Die zweite Lösung ist, Ihre config.json-Datei lokal zu laden und Ihre Objekte zu überschreiben.
Hinweis: Es kann auch vorkommen, dass die zurückgegebenen Assets nicht aktualisiert werden. Sie könnten eine Funktion schreiben, mit der Sie die Assets über die REST-API aus den Inhalten laden und sie auf dem Objekt platzieren. Beachten Sie jedoch, dass sich das Ergebnis des SDK von dem der REST-API unterscheidet, so dass wir diese Automatisierung nicht empfehlen. Die beste Vorgehensweise ist es, Ihre Struktur im Voraus so gut wie möglich zu definieren und die Experience in Showpad hochzuladen. Wenn Sie das nächste Mal entwickeln, stehen Ihnen die aktuellen Assets, die Sie in Ihren Inhalten definiert haben, zur Verfügung.
Die Lokalisierungsfunktion Ihrer Experience App ist sehr mächtig. Sie können verschiedene Sprachfelder für das gleiche Objekt hinzufügen oder einfach Ihre Experience App duplizieren und jedes Duplikat in eine andere Sprache übersetzen. Wir werden die Übersetzungen, die wir in unserer config.json definiert haben, verwenden, um unseren Titel festzulegen und unsere Buttons auszufüllen. Wenn unsere App fertig ist und hochgeladen wurde, kann der Admin diese Übersetzungen ändern, ohne programmieren zu müssen.
Fügen Sie folgende Funktion zu src/js/app.js hinzu und rufen Sie sie in der init-Funktion auf. Unsere App sollte nun diese Übersetzungen enthalten.
function translations () {
document.getElementsByTagName("h1")[0].innerHTML = window.labels.translations.title.value
document.querySelector('#search #search_submit').innerHTML = window.labels.translations.search_button.value
document.querySelector('#actions #actions_collection').innerHTML = window.labels.translations.add_to_collection_button.value
document.querySelector('#actions #actions_share').innerHTML = window.labels.translations.share_button.value
document.querySelector('#upload #upload_submit').innerHTML = window.labels.translations.upload_button.value
}
Als nächstes fügen wir die Möglichkeit hinzu, anhand von Tags nach Assets zu suchen. Sie können nach allen Assets suchen, die diesem Benutzer zugeordnet sind. Das bedeutet, dass die Suche nicht unbedingt auf die Tags beschränkt ist, die wir in unserer config.json definiert haben. Hierzu verwenden wir die Methode ShowpadLib.getAssetsByTags(). Alle ShowpadLib-Methoden werden vom SDK imitiert. Mithilfe des folgenden Links können Sie nachvollziehen, welche Einschränkungen bestehen und wie das erwartete Ergebnis aussehen soll.
- Fügen Sie die folgende Funktion zu src/js/app.js hinzu und benennen Sie sie als Init-Funktion.
function search () { document.querySelector('#search #search_submit').addEventListener('click', (e) => {
e.preventDefault()
ShowpadLib.getAssetsByTags([document.querySelector('#search input[type=text]').value], (assets) => {
console.log(assets) }) }) } - Wenn Sie nun nach einem Asset suchen, das Sie in der config.json definiert haben, sollten Sie es im Fenster console.log sehen.
Hinweis: Beachten Sie, dass ShowpadLib-Funktionen mit den gleichen Payloads bei schneller Wiederholung entprellt werden. Überprüfen Sie immer die zurückgegebene Antwort, um zu testen, ob der Aufruf erfolgreich war.
Jetzt wollen wir dem Benutzer unsere Ergebnisse anzeigen. Wir können einen Thumbnail abrufen, indem wir die ShowpadLib.getAssetPreviewUrl()-Methode verwenden, bei der wir die ID, den Slug und eine Größe unseres Thumbnails übergeben. Der Standardwert liegt bei 400 und der Maximalwert bei 1600.
Wir möchten auch, dass unser Benutzer das Asset öffnet, um zu sehen, ob es das richtige ist. Showpad verfügt über ein einzigartiges Dateischema, mit dem es diese Anfragen abfängt und den Asset Viewer öffnet. Diese URL ist wie folgt aufgebaut: showpad://file/ + assetSlug. Der Asset Viewer bietet auch native Funktionen wie das Teilen oder Hinzufügen von Assets zu einer Sammlung.
Unsere Ergebnisse enthalten auch ein Kontrollkästchen, um festzustellen, welche Assets gemeinsam genutzt oder zu einer Sammlung hinzugefügt werden sollen. Fügen Sie folgende Funktion zu src/js/app.js hinzu, um die Ergebnisse anzuzeigen. Rufen Sie diese Funktion im Rückruf Ihrer Suchergebnisse auf und übergeben Sie die Assets.
function displayResults (assets) {
document.getElementById('results').innerHTML = ''
for (let key in assets) {
let asset = assets[key]
let assetPreviewUrl = ShowpadLib.getAssetPreviewUrl(asset.id, asset.slug, 400);
let result = document.createElement('div')
result.className = 'result'
let html = '<a href=showpad://file/’ + asset.slug + '?modal=1>'
html += '<img src="' + ShowpadLib.getAssetPreviewUrl(asset.id,asset.slug,
400) + '" />'
html += '</a><input class="results_checkbox" type="checkbox" data-slug='
+ asset.slug +'>'
result.innerHTML = html
document.getElementById('results').appendChild(result);
}
}
Nachdem wir eine Suche durchgeführt haben, sollten die Ergebnisse nun angezeigt werden. Wir können auf das Bild klicken, um den nativen Asset Viewer von Showpad zu öffnen. Nun implementieren wir den Code, um die Assets zu verfolgen. Diese markieren wir als aktiv, indem wir das Kontrollkästchen aktivieren. Kopieren Sie die folgende Funktion und fügen Sie sie in src/js/app.js ein. Rufen Sie sie in Ihrer init()-Funktion auf.
function actions () {
document.querySelector('body').addEventListener('click', (e) => {
if (e.target.classList.contains('results_checkbox')) {
if (e.target.checked) {
activeAssets.push(e.target.dataset.slug)
} else {
activeAssets = activeAssets.filter(asset => asset !== e.target.dataset.slug);
}
}
})
}
Wie Sie sehen, speichern wir unsere Assets im activeAssets-Array. Fügen Sie dies wie folgt zum Anfang Ihrer Datei hinzu:
let activeAssets = []
Bei der Suche möchten wir sicherstellen, dass unsere bisherigen Ergebnisse nicht berücksichtigt werden, also löschen Sie Ihre activeAssets im Listener der Suchereignisse.
ShowpadLib.addAssetsToCollection & ShowpadLib.share
Nun fügen wir unser activeAssets-Array zu einer Sammlung hinzu. Dazu fügen wir dem Button einen Event Listener hinzu und überprüfen, ob unser activeAssets-Array nicht leer ist. Sofern dies nicht der Fall ist, rufen wir die Methode ShowpadLib.addAssetsToCollection() auf und übergeben unsere Assets. Der Rückruf liefert uns die ID der Sammlung, zu der unsere Assets hinzugefügt werden. Kopieren Sie den folgenden Code und fügen Sie ihn in die actions() Funktion in src/js/app.js ein.
document.querySelector('#actions #actions_collection').addEventListener('click', (e) => {
e.preventDefault()
if (activeAssets.length > 0) {
ShowpadLib.addAssetsToCollection(activeAssets, (collectionId) => {
if (collectionId) console.log('Assets werden der Sammlung hinzugefügt mit id: ' + collectionId)
})
}
})
Wir sollten eine Antwort des SDK sehen, die anzeigt, dass unsere Anfrage bearbeitet wurde. Genau das gleiche wollen wir auch mit unserem Share-Button tun. Dazu verwenden wir die Methode ShowpadLib.share(). Wenn wir Inhalte per Link oder E-Mail teilen wollen, muss ein Parameter übergeben werden. In unserem Beispiel entscheiden wir uns für E-Mail. Kopieren Sie den folgenden Code und fügen Sie ihn in die Funktion actions() in src/js/app.js ein.
document.querySelector('#actions #actions_share').addEventListener('click', (e)
=> {
e.preventDefault()
if (activeAssets.length > 0) {
ShowpadLib.share('email', activeAssets, (result) => {
if (result === 'success') console.log('Assets are shared with the client')
})
}
})
Hinweis: Sie können jederzeit überprüfen, welche Parameter vorhanden sind und welche erforderlich sind. Beachten Sie die Versionsnummer in der rechten oberen Ecke. Nicht alle Showpad-Plattformen verwenden die gleiche Version, so dass einigen von ihnen möglicherweise die Funktionen fehlen, die Sie benötigen. Unter folgendem Link können Sie überprüfen, welche Plattformen welche Version verwenden.
Wenn wir unsere App testen, sollte die Freigabe nun auch einen Rückruf zurückgeben. Wir haben eine App entwickelt, die in der Lage ist, Assets anhand von Tags zu suchen, die Assets zu öffnen, die Assets zu Sammlungen hinzuzufügen und die Assets zu teilen. Eine weitere wichtige Eigenschaft von benutzerdefinierten Apps ist die Generierung von Assets auf Basis von Eingaben und die Möglichkeit, diese offline zu speichern.
ShowpadLib.upload & ShowpadLib.displayToast
Mit der Upload-Methode können Benutzer generierte Inhalte auf myfiles hochladen. Dies erfordert einen Dateinamen und eine Datei und gibt einen Ereignisemitter mit mehreren Zuständen zurück. Wir generieren eine .txt-Datei aus einem Textfeld und übergeben sie an die Methode. Mit der Methode ShowpadLib.displayToast() können wir diese Statusse einem Benutzer mit einem nativen Toast auf jeder Plattform anzeigen. Kopieren Sie die folgende Funktion, fügen Sie sie in src/js/app.js ein und rufen Sie sie in der init-Funktion() auf.
function upload () {
document.querySelector('#upload #upload_submit').addEventListener('click', (e)
=> {
e.preventDefault()
const filename = 'my_first_experience_app.txt';
const file = new File([document.querySelector('#upload textarea').value], filename);
const upload = ShowpadLib.upload({
file: file,
filename: filename
})
upload.on('queued', () => {
ShowpadLib.displayToast({
type: "info",
text: "queued"
})
})
upload.on('uploading', (data) => {
ShowpadLib.displayToast({
type: "info",
text: "uploading (" + parseInt((data.bytesSent / data.bytesTotal)*100) + "%)"
})
})
upload.on('processing', () => {
ShowpadLib.displayToast({
type: "info",
text: "processing"
})
})
upload.on('success', (data) => {
ShowpadLib.displayToast({
type: "Erfolg",
text: "Erfolg"
})
})
})
}
Wenn Sie dies in unserer App testen, sehen Sie, dass das SDK mit dem Upload und mehreren Toast-Antworten reagiert. Das Datenobjekt im Success Handler gibt unser Asset zurück.
Hinweis: Wenn Sie offline sind, bleibt das Asset in der Warteschlange. Darauf zu warten, dass der Success Handler Ihre App freigibt, könnte Ihr Offline-Interface blockieren. Wir empfehlen eine nicht-obstruktive Benutzeroberfläche mit praktischen Statusbenachrichtigungen.
Zum jetzigen Zeitpunkt ist es nicht möglich, das hochgeladene Asset zu teilen oder einer Sammlung hinzuzufügen.
Stellen wir unsere App fertig! 🚢
Unsere App ist nun bereit für den Einsatz. Wir verwenden das SDK, um unsere App zu verpacken. Gehen Sie zu Ihrem Kommandozeilen-Tool in das Stammverzeichnis der App und geben Sie den folgenden Befehl ein:
showpad experience package
- Sie werden sehen, wie das SDK alle unsere Dateien überprüft und eine .showpad-Datei erstellt.
- Sie können nun zum Backend Ihrer Domäne gehen und den Channel Builder öffnen.
- Erstellen Sie einen neuen Channel mit dem Typ Experience App und wählen Sie unsere neu generierte .showpad-Datei aus.
- Nach dem Hochladen sollten Sie unsere App sehen, allerdings ohne initialisiertes JS. Dies liegt daran, dass wir unsere init()-Funktion in der Showpad.getShowpadApi()-Anfrage aufrufen, die in der Vorschau nicht ausgeführt wird. Dies funktioniert im Frontend.
Wenn Sie auf Bearbeiten klicken, sehen Sie die Struktur, die wir in der config.json definiert haben. Wie Sie sehen, können Sie die Übersetzungen verändern und unserer Anwendung Tags hinzufügen oder sie entfernen. - Klicken Sie auf Experience veröffentlichen und warten Sie, bis die Plattform unsere App veröffentlicht hat. Dies kann eine Minute dauern.
Wenn Sie jetzt zum Frontend wechseln und unseren neuen Channel öffnen, sollte die Tutorial-App in ihrer ganzen Pracht erscheinen. Nur zu, testen Sie alle Funktionen.
Sie finden die fertige Version in der Experience App Codebase, wo Sie Unterschiede mit Ihrer Codebase vergleichen können.
Die Entwicklerseiten sind Ihre erste Anlaufstelle bei der Entwicklung von Experience Apps.
Wir laden Sie ein, Ihre Fragen im Community- Teil zu stellen, damit andere Entwickler Ihre Fragen beantworten und jeder von jedem lernen kann.
Viel Spaß beim Programmieren!
