Was ist für Sie drin?
In diesem Tutorial wird erklärt, wie Sie eine erste Experience App mit einer Kombination von Showpad Entwickler Tools erstellen, die wir zur Verfügung stellen. Es setzt ein mittleres Wissen über Showpad und Front-End-Entwicklung voraus. Wenn Sie neu in der Entwicklung sind, empfehlen wir Ihnen, zunächst einen Überblick über die von uns bereitgestellten Entwickler Tools zu erhalten.
Wir werden eine Experience App mit folgenden Offline-Funktionen erstellen:
- Assets nach Tags suchen
- Hinzufügen von Assets zu einer Sammlung
- Assets teilen
- Assets hochladen
Sie finden mehrere Notizen, in denen wir Tipps, Tricks und Fakten für fortgeschrittene Entwickler erläutern. Sie können diese im Tutorial sicher überspringen. Am Ende dieser Seite finden Sie vorher und nachher ZIP-Dateien, die Ihnen den Start- und Endstatus des Projekts anzeigen.
Die folgenden Zeichen werden für die Verwendung in den Titeln von Dateien, die in einer benutzerdefinierten Experience App verwendet werden, nicht unterstützt: /, ?, #, @, !, $, &, *, +, ;, =.
Hinweis: Die aktuelle Windows-App verwendet IE11 als Wiedergabemaschine. Unsere App wird nicht funktionieren, da unsere Syntax ES6-artig ist.
Sie benötigen dies, um erfolgreich zu sein
- Administratorzugriff auf eine Showpad-Domain
- Markierte Assets, die für die Suche verwendet werden
- Showpad Ultimate-Lizenz
- KnotenJs , um unser SDK zu installieren
Der schnelle Weg zur Großartigkeit
- Installieren Sie das 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
- Lassen Sie uns unsere App veröffentlichen
- Endnote
Tun Sie dies Schritt für Schritt
Wir haben eine ZIP-Datei mit unserer Ordnerstruktur und einigen vorhandenen Dateien vorbereitet. Laden Sie dieses Experience App Boilerplate-ZIP herunter und extrahieren Sie es in einen lokalen Ordner auf Ihrem System.
Sie können dies mit dem folgenden Befehl tun:
npm i @ showpad/SDK -g
Sie benötigen einen OAuth-Client, um sich und unsere Anwendung zu authentifizieren.
- Gehen Sie zum Showpad-Backend, klicken Sie auf das Zahnrad und drücken Sie Integrationen.
- Klicken Sie auf OAuth-Clients verwalten und drücken Sie die Plus-Taste, um einen neuen zu erstellen. Verwenden Sie die folgenden Parameter für Ihren OAuth-Client:
- Name: Entwickler-Client
- URL umleiten: https://yourdomain.showpad.biz
- Beschreibung: OAuth-Client zum Entwickeln von Experience Apps
- Webseite: https://yourdomain.showpad.biz
- Diese Clients müssen: Aktivieren Sie alle Kontrollkästchen
Wir haben nun unseren OAuth-Client, müssen jedoch unseren Benutzer für diesen Client authentifizieren.
- Ändern Sie die fett gedruckten Parameter dieser URL und fügen Sie sie in eine Browser-Registerkarte 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 nun für diesen Client authentifiziert.
Wir werden das SDK verwenden, um unsere Authentifizierungsdatei zu erstellen.
- Gehen Sie in Ihrem Befehlzeilentool auf unser Verzeichnis und verwenden Sie den folgenden Befehl.
Showpad auth
- Einige Fragen werden erscheinen. Ihr Showpad-Benutzername ist Ihre E-Mail-Adresse. Im Verzeichnis sollte sich eine neue Datei .showpadconfig.JSON befinden.
Die manifest.JSON-Datei enthält allgemeine Informationen zu Ihrer Experience App. Stellen Sie sicher, dass Ihre Kennung für jede von Ihnen erstellte Experience App einzigartig ist, und erhöhen Sie die Versionsnummer jedes Mal, wenn Sie eine neue Version auf Showpad hochladen. Kopieren Sie die folgende Struktur in src/manifest.JSON. Sie können den Autor auf Ihren Namen einstellen.
{
"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 Konfiguration.JSON-Datei bestimmt die Struktur der Beschriftungen und Inhalte, die vom Showpad Administrator geändert werden können.
- Beschriftungen können Einstellungen oder Übersetzungen sein und sind textbasiert.
- Der Inhalt definiert die Assets, auf die Ihre App und der Ihrer App zugewiesene Benutzer Zugriff haben sollen. Diese Assets sind offline verfügbar. Stellen Sie sicher, dass die Datei config.JSON keine Objektschlüssel enthält, die von Showpad reserviert werden könnten, z. B. Typ, Wert usw. Wenn sie inder folgenden Liste aufgeführt sind, können Sie sie nicht als benutzerdefinierten Schlüssel verwenden.
Wir werden einige Übersetzungen in die Beschriftungen einfügen und Assets mit Tags anfordern, nach denen wir später suchen können. Kopieren Sie die folgende Struktur in src/config.JSON und ändern Sie [„tag1“, „tag2“, „tag3“] mit Tags, die Sie tatsächlich im Backend verwenden. Stellen Sie sicher, dass Assets mit den von Ihnen eingegebenen Tags vorhanden sind.
{
"version": 1,
"labels": {
"translations": {
"title": {
"value": "Tutorial",
"description": "Title"
},
"search_button": {
"value": "Suche",
"description": "Suchen-Schaltfläche"
},
"add_to_collection_button": {
"value": "Zur Sammlung hinzufügen",
"description": "Zur Sammlung hinzufügen-Schaltfläche"
},
"share_button": {
„value“: „Teilen"
„description“: „Teilen-Schaltfläche“
},
„upload_button“: {
„value“: „Hochladen“,
„description“: „Hochladen-Schaltfläche“
}
}
},
„contents“: {
„assets": {
„search“: {
„type“: „Tags“,
„value“: {„oder“: [„Tag1“, „Tag2“, „Tag3“]},
„description“: „Durchsuchbare Assets“
}
}
}
}
Die index.html ist der Einstiegspunkt unserer Experience App. Hier können Sie Ihre Struktur einrichten und alle erforderlichen Ressourcen wie CSS und JS hinzufügen. Die Boilerplate enthält bereits unsere Struktur. Jetzt da alles ist, wo es sein sollte, können wir mit der Entwicklung unserer App loslegen.
Zum Entwickeln 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 nachgeahmt, was auch auf der Plattform der Fall sein wird.
- Geben Sie Folgendes in Ihr Befehlzeilentool ein (immer noch im Stamm unseres Verzeichnisses), um den Server zu starten.
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 mit einem Framework wie React entwickeln möchten, können Sie Ihren Entwicklungsserver an einem anderen Port starten (z. B. 8080) und den Showpad Server darauf verweisen. Stellen Sie sicher, dass Ihr öffentlicher Pfad relativ ist.
showpad experience serve --host http://localhost:8080
Wir möchten wissen, wann Showpad unsere Anwendung geladen hat. Wenn wir versuchen, Methoden der ShowpadLib früher aufzurufen, schlägt dies fehl.
- Als nächstes möchten wir unsere Konfiguration aus config.JSON laden, um auf unsere Labels, Inhalte und Assets zuzugreifen. Das Assets-Objekt enthält die Assets, die Sie im Inhalt definiert haben. Diese Assets enthalten alle erforderlichen Informationen für die ShowpadLib-Methoden, die wir verwenden werden.
- Sobald die Konfiguration geladen ist, setzen wir diese Objekte auf das Fenster, 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: {
'Autorisierung': 'Inhaber' + apiConfig.accessToken,
'Inhaltstyp': '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. Dies ist das SDK, das uns sagt, dass es unsere Assets nachahmt.
Hinweis: Bei 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 beispielsweise bereits eine Version zum Testen hochgeladen haben. Sie können dies auf zwei Arten lösen. Die erste besteht darin, die Kennung in Ihrer App zu ändern. Die zweite besteht darin, Ihre config.JSON lokal zu laden und Ihre Objekte zu überschreiben.
Hinweis: Es kann auch vorkommen, dass die zurückgegebenen Assets nicht aktualisiert werden. Sie können eine Funktion schreiben, in der Sie die Assets aus dem Inhalt über die REST-API laden und auf dem Objekt platzieren. Beachten Sie, dass sich das Ergebnis des SDK von der REST-API unterscheidet, sodass wir diese Automatisierung nicht fördern. Die beste Vorgehensweise besteht darin, Ihre Struktur im Voraus so gut wie möglich zu definieren, die Experience auf Showpad hochzuladen und bei der nächsten Entwicklung über die aktuellen Assets zu verfügen, die Sie in Ihren Inhalten definiert haben.
Die Lokalisierung Ihrer Experience App ist sehr leistungsfähig. Sie können verschiedene Sprachfelder für dasselbe Objekt hinzufügen oder einfach Ihre Experience App duplizieren und jedes in eine andere Sprache übersetzen. Wir werden die Übersetzungen verwenden, die wir in unserer config.JSON definiert haben, um unseren Titel festzulegen und unsere Schaltflächen zu füllen! Wenn unsere App fertig ist und hochgeladen wurde, kann der Administrator diese Übersetzungen ohne Codierung ändern.
Fügen Sie src/js/app.js die folgende Funktion 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
}
Das nächste, was wir hinzufügen, ist die Möglichkeit, nach Assets anhand von Tags zu suchen. Sie können nach allen Assets suchen, die diesem Benutzer zugewiesen sind. Dies bedeutet, dass es nicht unbedingt in den Tags enthalten ist, die wir in unserer config.JSON definiert haben. Dazu verwenden wir die ShowpadLib.getAssetsByTags() -Methode. Alle ShowpadLib-Methoden werden vom SDK nachgeahmt. Unter dem folgenden Link können Sie sehen, welche Einschränkungen bestehen und wie das erwartete Ergebnis aussehen sollte.
- Fügen Sie die folgende Funktion hinzu: src/js/app.js und rufen Sie es in der Init-Funktion auf.
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 jetzt nach einem Asset suchen, das Sie in der Datei config.JSON definiert haben, sollten Sie es in der Konsole sehen.Protokollfenster.
Hinweis : Beachten Sie, dass ShowpadLib-Funktionen mit derselben Nutzlast bei schneller Wiederholung entprellt werden. Überprüfen Sie immer die zurückgegebene Antwort, um festzustellen, ob ein Aufruf eingegangen ist.
Wir möchten dem Benutzer nun unsere Ergebnisse anzeigen. Wir können eine Miniaturansicht mit der ShowpadLib.getAssetPreviewUrl() -Methode abrufen, bei der wir die ID, den Slug und die Größe unserer Miniaturansicht übergeben. Der Standardwert hierfür ist 400 und der Maximalwert ist 1600.
Wir möchten auch, dass unser Benutzer das eigentliche Asset öffnet, um festzustellen, ob es das richtige ist. Showpad verfügt über ein eindeutiges Dateischema, in dem diese Anforderungen abgefangen und der Asset-Viewer geöffnet wird. Diese URL wird folgendermaßen aufgebaut: showpad://file/ + assetSlug. Der Asset Viewer bietet auch native Funktionen wie das Freigeben oder Hinzufügen von Assets zu einer Sammlung.
Unsere Ergebnisse enthalten auch ein Kontrollkästchen, mit dem Sie ermitteln können, welche Assets wir freigeben oder einer Sammlung hinzufügen möchten. Fügen Sie die folgende Funktion hinzu: src/js/app.js , um unsere Ergebnisse anzuzeigen. Rufen Sie diese Funktion im Rückruf Ihrer Suchergebnisse auf und übergeben Sie die Assets an sie.
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 eingereicht haben, sollten nun Ergebnisse angezeigt werden. Wir können auf das Bild klicken, um den nativen Showpad-Asset-Viewer zu öffnen. Wir implementieren nun Code, um die Assets zu verfolgen, die wir durch Aktivieren des Kontrollkästchens als aktiv markieren. Kopieren Sie die folgende Funktion in src/js/app.js und 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 können, speichern wir unsere Assets im Array activeAssets. Fügen Sie dies wie folgt oben in Ihre Datei ein:
let activeAssets = []
Bei der Suche möchten wir sicherstellen, dass unsere vorherigen Ergebnisse nicht berücksichtigt werden. Löschen Sie daher Ihre activeAssets im search event listener.
ShowpadLib.addAssetsToCollection & ShowpadLib.share
Wir möchten nun unser activeAssets-Array zu einer Sammlung hinzufügen. Dazu fügen wir der Schaltfläche einen Event-Listener hinzu und stellen sicher, dass unser activeAssets-Array nicht leer ist. Wenn nicht, rufen wir die ShowpadLib.addAssetsToCollection() -Methode auf und übergeben unsere Assets. Der Rückruf gibt uns die ID der Sammlung an, zu der unsere Assets hinzugefügt wurden. Kopieren Sie den folgenden Code und fügen Sie ihn in die action()-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 mit der ID hinzugefügt: ' + collectionId)
})
}
})
Wir sollten eine Antwort vom SDK sehen, die angibt, dass unser Aufruf durchgegangen ist. Genau das wollen wir auch mit unserer Teilen-Schaltfläche tun. Dafür verwenden wir die ShowpadLib.share() -Methode. Wir müssen einen Parameter übergeben, wenn wir per Link oder E-Mail teilen möchten. In unserem Beispiel wählen wir E-Mail. Kopieren Sie den folgenden Code in die actions()-Funktion in src/js/App.js.
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 werden mit dem Programm geteilt')
})
}
})
Hinweis: Hier können jederzeit überprüfen, welche Parameter vorhanden sind und welche erforderlich sind. Beachten Sie die Versionsnummer in der oberen rechten Ecke. Nicht alle Showpad-Plattformen verwenden dieselbe Version, sodass einige von ihnen möglicherweise die von Ihnen benötigten Funktionen nicht haben. Sie können sich auf den folgenden Link verweisen, und nachsehen welche Plattformen welche Version haben.
Wenn wir unsere App testen, sollte das Teilen jetzt auch einen Rückruf zurückgeben. Wir haben eine App erstellt, die nach Assets anhand von Tags suchen, die Assets öffnet, die Assets zu Sammlungen hinzufügt und die Assets teilen kann. Ein weiterer wichtiger Punkt bei benutzerdefinierten Apps ist die Generierung von Assets auf Basis von Eingaben und die Möglichkeit, diese offline zu speichern.
ShowpadLib.upload & ShowpadLib.displayToast
Die Hochladen-Methode ermöglicht es Benutzern, generierte Inhalte in Meine Dateien hochzuladen. Es erfordert einen Dateinamen und eine Datei und gibt einen Event-Emitter zurück, der mehrere Stadien hat. Wir generieren eine .txt-Datei aus einem Textbereich-Feld und übermitteln sie an die Funktion. Mit der ShowpadLib.displayToast()-Methode können wir dem Benutzer diese Status mit einem nativen Toast auf jeder Plattform anzeigen. Kopieren Sie die folgende Funktion in src/js/App.js 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: "success",
text: "success"
})
})
})
}
Wenn Sie dies in unserer App testen, sehen Sie, dass das SDK mit dem Hochladen und mehreren Toastantworten reagiert. Das Datenobjekt im Success-Handler gibt unser Asset zurück.
Hinweis: Wenn das Asset offline ist, bleibt es in der Warteschlange. Das Warten auf die Freigabe Ihrer App durch den Success-Handler kann Ihre Benutzeroberfläche offline blockieren. Wir empfehlen eine nicht behindernde Benutzeroberfläche mit ordnungsgemäßen Benachrichtigungen über den Status.
Zum Zeitpunkt des Schreibens ist es nicht möglich, das hochgeladene Asset freizugeben oder einer Sammlung hinzuzufügen.
Unsere App kann nun verteilt werden. Wir werden das SDK verwenden, um unsere App zu verpacken. Gehen Sie zu Ihrem Befehlzeilentool 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 Domain gehen und den Channel Builder öffnen.
- Erstellen Sie einen neuen Kanal mit dem Typ Experience App und wählen Sie unsere neu generierte .Showpad-Datei aus.
- Nach dem Hochladen sollte unsere App angezeigt werden, jedoch ohne dass der JS initialisiert wurde. Dies liegt daran, dass wir unsere init()-Funktion im Showpad.getShowpadApi()-Aufruf aufrufen, die in der Vorschau nicht ausgeführt wird. Dies wird im Frontend funktionieren.
Wenn Sie auf Bearbeiten klicken, wird die in der Datei config.JSON definierte Struktur angezeigt. Wie Sie sehen, können Sie die Übersetzungen ändern und Tags zu unserer Anwendung hinzufügen und daraus entfernen. - Klicken Sie auf Experiences veröffentlichen und warten Sie, dass die Plattform unsere App freigibt. Dies kann eine Minute dauern.
Wenn Sie nun zum Frontend gehen und unseren neuen Kanal öffnen, sollte die Tutorial-App in ihrer ganzen Pracht erscheinen. Fahren Sie fort und testen Sie alle Funktionalitäten.
Die fertige Version finden Sie hier: Experience App Codebasis, um Unterschiede mit Ihrer Codebasis zu vergleichen.
Die Entwicklerseiten sind Ihre Anlaufstelle bei der Entwicklung von Experience Apps.
Wir heißen Sie herzlich willkommen , Ihre Fragen im Gemeinschaftsteil zu stellen, damit andere Entwickler Ihre Fragen beantworten und jeder von jedem lernen kann.
Viel Spaß beim Codieren!
