Guide: Byg Apps med Adobe App Builder

I en verden, hvor digitale oplevelser er altafgørende, søger udviklere konstant efter robuste værktøjer til at skabe skalerbare og integrerede applikationer. Adobe App Builder, kombineret med den centrale Adobe Developer Console, tilbyder et sådant økosystem, der gør det muligt at bygge skræddersyede løsninger, der udvider og forbedrer Adobes produkter. Denne guide vil føre dig gennem processen med at opsætte, udvikle og implementere din første App Builder applikation, fra de indledende skridt i Developer Console til de afsluttende implementeringsfaser.

Adobe App Builder er designet til at give udviklere mulighed for at skabe native cloud-applikationer, der kører på Adobes serverless-platform, Adobe I/O Runtime. Dette åbner døren for en lang række anvendelsesmuligheder, lige fra dynamisk webindhold til automatiserede arbejdsgange. Ved at udnytte Adobes API'er og SDK'er kan du integrere dybt med produkter som Adobe Experience Manager, Adobe Target og mange flere.

Hvad er Adobe Developer Console?

Adobe Developer Console er din indgang til Adobes udviklerøkosystem. Det er en centraliseret webbaseret platform, der giver dig adgang til Adobe API'er, SDK'er og udviklerværktøjer. Det er her, du administrerer dine projekter, opretter legitimationsoplysninger og konfigurerer adgang til de forskellige Adobe-tjenester, din applikation skal interagere med. For App Builder applikationer er Developer Console afgørende for at opnå adgang til Adobe I/O Runtime-legitimationsoplysninger, som er nødvendige for at implementere dine serverless-funktioner, samt API-legitimationsoplysninger, hvis din applikation skal kalde Adobe API'er.

Hvert projekt i Developer Console kan have flere workspaces. Disse workspaces fungerer som isolerede miljøer til forskellige implementeringsstadier – tænk på dem som Udvikling, Kvalitetssikring (Q/A), Staging og Produktion. Hver workspace kan have unikke tjenester tilsluttet og separate legitimationsoplysninger, hvilket sikrer, at dine udviklingsmiljøer ikke påvirker dit produktionsmiljø. Standard workspaces er typisk 'Production' og 'Stage', men du kan nemt tilføje flere efter behov.

Hvorfor bruge Adobe App Builder?

App Builder er ikke bare et værktøj; det er en platform, der muliggør en række kraftfulde løsninger, der kan optimere dine arbejdsgange og forbedre brugeroplevelserne:

• Dynamisk webindhold uden ventetid: Byg headless- og single-page-applikationer (SPA'er) for rigt, dynamisk webindhold, der indlæses lynhurtigt. Dette sikrer en flydende og responsiv brugeroplevelse, hvilket er afgørende i nutidens digitale landskab.
• Levering af relevante anbefalinger: Gå ud over standardintegrationer mellem Adobe Experience Manager og Adobe Target. Med App Builder kan du skabe skræddersyede mikroservices, der leverer unikke og hyperrelevante anbefalinger baseret på specifikke brugerdata og forretningslogik.
• Nem aktivmigrering: Flyt store mængder aktiver fra et eksternt Digital Asset Management (DAM) system ind i Adobe Experience Manager Assets uden at overbelaste AEM-ressourcerne. Dette er ideelt for virksomheder med store arkiver af medier og dokumenter.
• Automatiske aktivopdateringsmeddelelser: Udnyt hændelsesbaserede triggere til automatisk at give marketingfolk besked, når et aktiv ændres, tilføjes eller fjernes. Dette sikrer, at alle teammedlemmer er opdaterede og kan reagere prompte på ændringer i aktivbiblioteket.

Kom godt i gang: Opsætning af din App Builder applikation

At starte med App Builder kræver en kombination af opsætning i Adobe Developer Console og brug af kommandolinjeværktøjet (CLI) lokalt. Følg disse trin for at komme i gang:

Trin 1: Forberedelse af dit miljø

Før du dykker ned i udviklingen, er det afgørende at sikre, at dit lokale miljø og dine værktøjer er opdaterede, og at du har den nødvendige adgang til App Builder. Dette inkluderer at tjekke din adgang i Adobe Developer Console og opdatere din Adobe I/O CLI. Du kan tjekke din CLI-version med aio -v og opdatere den med npm install -g @adobe/aio-cli, efterfulgt af aio update for at sikre, at alle plugins er opdaterede.

Trin 2: Oprettelse af et nyt projekt i Developer Console

Dit App Builder-projekt starter i Adobe Developer Console. Her opretter du grundlaget for din applikation og dens interaktion med Adobes tjenester.

1. Naviger til Adobe Developer Console.
2. Brug IMS Org Switcher i øverste højre hjørne til at vælge den korrekte IMS-organisation.
3. Klik på Quick Start og vælg muligheden Create project from template. Hvis du ikke ser denne mulighed, skal du bekræfte din IMS-organisation; du har muligvis ikke adgang til App Builder endnu.
4. Vælg App Builder fra listen over skabeloner.
5. Indtast en Project Title og et App Name. Projektets titel identificerer projektet i Developer Console og CLI'en, mens applikationens navn er dens unikke identifikator. Bemærk, at applikationens navn ikke kan ændres, når projektet er oprettet.
6. Sørg for, at afkrydsningsfeltet "Include Runtime with each workspace" er markeret. Dette sikrer, at hver workspace automatisk får sit eget unikke Adobe I/O Runtime-namespace, hvilket er ideelt for udviklere, der arbejder i separate miljøer.
7. Klik på Save. Du vil nu se et nyt projekt genereret med to standard workspaces: 'Production' og 'Stage'.

Trin 3: Log ind via CLI

Når dit projekt er opsat i Developer Console, skal du forbinde din lokale udviklingsmaskine til Adobe-økosystemet via CLI'en:

1. Åbn din Terminal eller Kommandoprompt.
2. Indtast kommandoen: aio login
3. En browserfane vil åbne og bede dig om at logge ind med dit Adobe ID. Følg anvisningerne. Hvis browseren ikke åbner automatisk, kopier/indsæt den viste URL i din browser.
4. Efter succesfuld login kan du lukke browserfanen og vende tilbage til Terminalen. Du vil se en bruger-token-streng vist i terminalen. Denne token gemmes automatisk i CLI-konfigurationen, så CLI'en kan kommunikere med Adobe Developer Console.

Trin 4: Initialisering af den nye app med CLI'en

Med din CLI logget ind kan du nu initialisere din App Builder applikation lokalt. Der er flere måder at gøre dette på, afhængigt af dine legitimationsoplysninger og dit formål:

4.1 Initialisering med Udvidelsespunkter (for Enterprise brugere)

Hvis du er en berettiget virksomhedsbruger og ønsker at starte med specifikke Adobe-produktintegrationer, kan du initialisere projektet med udvidelsespunkter:

I Terminalen, naviger til den mappe, hvor du vil initialisere dit projekt, og skriv:

aio app init <app_name>

Du vil blive bedt om at vælge din organisation, dit projekt og den workspace, du lige har oprettet. Derefter vælger du de udvidelsespunkter, du ønsker at implementere, f.eks. "DX Experience Cloud SPA v1" eller "DX Asset Compute Worker v1". CLI'en vil derefter generere de nødvendige filer og installere npm-afhængigheder.

4.2 Initialisering af et tomt projekt (for Enterprise brugere)

Hvis du foretrækker en mere modulær tilgang, kan du initialisere et tomt projekt og derefter tilføje funktioner:

I Terminalen, naviger til den mappe, hvor du vil initialisere dit projekt, og skriv:

aio app init <app_name> --standalone-app

Du vil blive bedt om at vælge organisation, projekt og workspace. Derefter får du mulighed for at aktivere specifikke funktioner som "Actions: Deploy Runtime actions" (til backend serverless-funktioner), "Events: Publish to Adobe I/O Events", "Web Assets: Deploy hosted static assets" (til frontend SPA'er) og "CI/CD: Include GitHub Actions based workflows". For denne tutorial anbefales det at vælge dem alle. Du kan også vælge at inkludere eksempelaktioner (f.eks. Generic, Adobe Analytics) og den type UI, du ønsker (React Spectrum 3 UI eller Raw HTML/JS UI).

4.3 Initialisering med en Console konfigurationsfil

Hvis du ikke har direkte adgang til Adobe Developer Console, men har fået en konfigurationsfil fra en administrator, kan du bruge den til at initialisere dit projekt:

I Terminalen, naviger til den mappe, hvor du vil initialisere dit projekt, og skriv:

aio app init <app_name> --import <path_to_config_file>

CLI'en vil bruge informationen fra den downloadede fil til at forudfylde værdier i dine .env og .aio filer. Den eneste forskel er, at console.json-filen ikke vil være til stede, da den blev brugt til at generere projektet.

4.4 Initialisering uden legitimationsoplysninger

For udviklere, der kun ønsker at inspicere koden uden at køre eller implementere applikationen, er der en hurtig måde at generere et eksempelprojekt på:

I Terminalen, naviger til den mappe, hvor du vil initialisere dit projekt, og skriv:

aio app init <app_name> -y

-y-flaget springer alle spørgsmål over og genererer et simpelt prøveprojekt med kun en generisk eksempelaktion. Bemærk, at du ikke vil kunne køre eller implementere denne applikation som standard, da der ikke er angivet legitimationsoplysninger.

Anatomien af en App Builder applikation

Når dit projekt er initialiseret, vil du se en række mapper og filer. Forståelse af denne struktur er afgørende for effektiv udvikling:

• src: Indeholder individuelle mapper for hvert udvidelsespunkt, du har valgt. Disse mapper indeholder både backend-aktioner (serverless code) og frontend-ressourcer (f.eks. React-kode). Hver mappe indeholder en ext.config.yaml-fil, der definerer handlinger og udvidelseskonfigurationer for det specifikke udvidelsespunkt.
• test: Denne mappe er dedikeret til enheds- og integrationstest af dine backend-aktioner.
• e2e: Indeholder end-to-end tests for din applikation.
• app.config.yaml: Den overordnede konfigurationsfil, der samler alle de individuelle ext.config.yaml-filer til en omfattende konfiguration under applikationsbygningen.
• lib: Bruges til at opbevare delte hjælpefunktioner og moduler, der kan genbruges på tværs af forskellige udvidelsespunkter.
• package.json: Standard Node.js-fil, der beskriver projektdefinitionen og forskellige metadata, herunder projektets afhængigheder, som administreres af npm.
• .aio: Indeholder konfigurationsvariabler, der er nyttige for CLI'en til at facilitere appen. Denne fil bør ikke committes til et versioneringssystem som Git, da den kan indeholde miljøspecifikke indstillinger.
• .env: Indeholder miljøvariabler, der er nyttige for appen under udvikling, såsom Adobe I/O Runtime-legitimationsoplysninger og Adobe Produkt API-nøgler. Ligesom .aio bør denne fil ikke deles eller committes, da den indeholder følsomme oplysninger. Hvis du har opsat legitimationsoplysninger for de valgte workspaces, vil nogle værdier som AIO_runtime_auth og AIO_runtime_namespace være forudfyldt.

Udvikling af applikationen

Med projektstrukturen på plads er du klar til at udvikle din applikation. Adobe CLI tilbyder flere kommandoer til at køre og teste din app lokalt.

6.1 Kør applikationen lokalt

Den mest almindelige kommando for lokal udvikling er aio app dev. Den giver en hurtig feedback-loop med hot reloading af både backend-aktioner og frontend-kode. Dette betyder, at ændringer i din kode automatisk afspejles i din applikation uden at skulle genstarte serveren.

6.2 Accepter certifikatet (ved første brug)

Første gang du kører din App Builder applikation lokalt, vil du sandsynligvis se en meddelelse om et selvsigneret udviklingscertifikat. Adobe bruger et udviklings-SSL-certifikat for sikker kommunikation. Du skal acceptere dette certifikat i din browser for at kunne få adgang til din applikation. Naviger til https://localhost:9080 i din browser, klik på 'Avanceret' og vælg at fortsætte til localhost (usikker) for at acceptere certifikatet. Du skal muligvis afslutte den aktuelle proces og køre aio app dev eller aio app run igen efter accept.

6.3 Adgang til applikationen på localhost

Når applikationen kører, vil CLI'en vise to URL'er:

• Den første URL (f.eks. https://localhost:9080) viser din standalone applikation lokalt.
• Den anden URL (f.eks. https://experience.adobe.com/?devMode=true#/custom-apps/?localDevUrl=https://localhost:9080) placerer din lokale applikation i kontekst af Experience Cloud UI til forhåndsvisning. Dette er særligt nyttigt, hvis din app skal integreres dybt med Experience Cloud.

Det er vigtigt at bemærke, at ændringer i din .env-fil ikke opdateres i realtid under kørsel. Hvis du ændrer miljøvariabler, skal du genstarte applikationen. Når appen kører, sikkerhedskopieres den originale .env-fil, og en ny skrives med specifikke værdier. Når du afslutter processen (f.eks. med CTRL+C), gendannes den originale .env-fil.

6.4 Afprøv prøveapplikationen

Når du tilgår https://localhost:9080, vil du se prøveapplikationen implementeret. Denne simple SPA indeholder links til dokumentation og giver dig mulighed for at køre dine backend-aktioner til tests. Du kan vælge den handling, du ønsker at kalde, og også sende anmodningsheaders og parametre fra de tilsvarende inputfelter i SPA UI'en.

Som standard kræver alle aktioner Authorization og x-gw-ims-org-id i headers. Dette skyldes require-adobe-auth-annotationen, som er sat til true for sikkerheds skyld. For at kalde en handling skal du bruge en gyldig bruger-token og den tilsvarende organisations-ID. Din token kan hentes fra CLI'en via aio login, og organisations-ID'et (f.eks. some_hash@AdobeOrg) kan findes i workspace-detaljerne på Adobe Developer Console eller via aio console org list. Formatér dem som {"Authorization":"Bearer <token_from_cli>","x-gw-ims-org-id":"<org-id-from-console>"} og indsæt i headers-feltet.

Bemærk, at andre eksempelaktioner, såsom dem der interagerer med Adobe Analytics eller Experience Platform, kræver yderligere parametre som apiKey eller companyId. Disse skal konstrueres i formatet {"key": "value"} og indsættes i parametre-feltet. Du kan finde de nødvendige parametre ved at undersøge aktionskoden i actions-mappen eller i den relevante produktdokumentation.

6.5 Fejlfinding af applikationen

aio app dev-kommandoen er designet til at understøtte fejlfinding. Den giver dig mulighed for at udvikle og debugge Adobe Runtime-aktioner i dit foretrukne IDE (f.eks. VSCode) med en hurtig feedback-loop. Dette inkluderer trinvis fejlfinding med længere timeouts, LiveReload for web-aktioner og øjeblikkelig logudgang til Terminalen. Det er vigtigt at huske, at aio app dev ikke fuldt ud emulerer Adobe I/O Runtime-miljøet, og nogle miljøvariabler kan opføre sig anderledes lokalt end i det implementerede miljø.

6.6 Hent applikationslogs

For at se logs fra din applikation efter at have kørt aio app run eller efter implementering (aio app deploy), kan du bruge kommandoen aio app logs. Som standard hentes kun logs fra den seneste aktivering. For en mere omfattende liste kan du bruge --limit-flaget til at definere antallet af nylige aktiveringer, der skal hentes.

6.7 Test applikationen

Den bootstrapped applikation leveres med eksempelimplementeringer for både enheds- og end-to-end tests. Du kan udføre disse tests lokalt ved hjælp af aio app test (for enhedstests) eller aio app test -e (for end-to-end tests). Adobe bruger JestJS til enhedstest af CLI, SDK og bootstrapped applikationer, men du kan ændre implementeringen til dit foretrukne framework, hvis det ønskes. Det er vigtigt at opdatere testene, når du ændrer og udvider din applikationskode.

Implementering af applikationen

Når din applikation er klar, kan den implementeres fuldt ud til din udviklingsworkspace med en enkelt kommando:

aio app deploy

Denne kommando kan tage et par minutter, da CLI'en bygger og implementerer bag kulisserne:

• Aktionerne defineret i app.config.yaml implementeres til Adobe I/O Runtime.
• De byggede frontend-filer og aktiver implementeres til Content Delivery Network (CDN), der leveres med App Builder.

CLI-outputtet vil vise detaljer om processen og give dig to URL'er til den implementerede applikation: én for CDN-hosten og én for Experience Cloud Shell-konteksten. For at fjerne din implementerede app kan du bruge kommandoen aio app undeploy.

Ofte stillede spørgsmål (FAQ)

Her er svar på nogle af de mest almindelige problemer, du kan støde på under udviklingen:

Hvordan opdaterer jeg CLI og plugins?

Sørg altid for, at din Adobe CLI og alle plugins er opdaterede. Du kan tjekke din CLI-version med aio -v og sammenligne den med den seneste version på npm (npm show @adobe/aio-cli version). Hvis din CLI er forældet, opdater den ved at køre npm install -g @adobe/aio-cli. Derefter kan du blot køre aio update for at sikre, at alle kerneplugins er opdaterede.

Hvad betyder "error: cannot validate token, reason: missing authorization header"?

Denne fejl indikerer, at du ikke har angivet en korrekt autorisationsheader til en handling, der forventede en. Som beskrevet under "Afprøv prøveapplikationen" skal du inkludere Authorization-headeren med en gyldig bruger-token og x-gw-ims-org-id-headeren med dit organisations-ID. Dette er en sikkerhedsforanstaltning for at sikre, at kun autoriserede brugere kan kalde dine handlinger.

Hvad betyder "error: missing parameter(s) 'apiKey,companyId'"?

Denne fejl opstår, når du forsøger at kalde en handling, der kræver specifikke parametre (som apiKey eller companyId), men du ikke har angivet dem. Nogle eksempelaktioner og Adobe API'er kræver yderligere data for at fungere korrekt. Du skal undersøge aktionskoden eller produktdokumentationen for at finde ud af, hvilke parametre der er nødvendige, og derefter sende dem i det korrekte JSON-format i parametre-inputfeltet i din SPA UI.

Med denne omfattende guide er du nu godt rustet til at navigere i Adobe App Builder og Developer Console-økosystemet. Fortsæt med at udforske Adobes ressourcer for flere kodeeksempler og use cases for at maksimere potentialet i dine applikationer.

Hvis du vil læse andre artikler, der ligner Guide: Byg Apps med Adobe App Builder, kan du besøge kategorien Teknologi.