Gestione degli host AEM

Questo esempio, basato liberamente sull'app AEM Headless React, illustra come configurare le richieste API GraphQL dell'AEM per connettersi a diversi servizi AEM in base alle variabili di ambiente.

Le app React devono utilizzare il client headless AEM per JavaScript per interagire con le API GraphQL AEM. Il client AEM Headless fornito dal client AEM Headless per JavaScript deve essere inizializzato con l’host del servizio AEM a cui si connette.

File di ambiente React

React utilizza file di ambiente personalizzati, o .env file, memorizzati nella directory principale del progetto per definire valori specifici della build. Ad esempio, il file .env.development contiene i valori utilizzati per durante lo sviluppo, mentre .env.production contiene i valori utilizzati per le build di produzione.

• .env.development

# Environment variable used to specify the AEM service the React app will connect to when running under this profile
REACT_APP_AEM_HOST=https://publish-p123-e456.adobeaemcloud.com
...

È possibile specificare .env file per altri usi 🔗 tramite il postfix di .env e un descrittore semantico, ad esempio .env.stage o .env.production. È possibile utilizzare file .env diversi durante l'esecuzione o la creazione dell'app React impostando REACT_APP_ENV prima di eseguire un comando npm.

Ad esempio, package.json di un'app React può contenere la seguente configurazione scripts:

• package.json

...
"scripts": {
  "build:development": "REACT_APP_ENV=development npm run build",
  "build:stage": "REACT_APP_ENV=stage npm run build",
  "build:production": "REACT_APP_ENV=production npm run build"
},
...

Client AEM headless

Il client AEM headless per JavaScript contiene un client AEM headless che invia richieste HTTP alle API GraphQL dell'AEM. Il client headless AEM deve essere inizializzato con l'host AEM con cui interagisce, utilizzando il valore del file .env attivo.

• src/api/headlessClient.js

const { AEMHeadless } = require('@adobe/aem-headless-client-js');
...
// Get the environment variables for configuring the headless client,
// specifically the `REACT_APP_AEM_HOST` which contains the AEM service host.
const {
    REACT_APP_AEM_HOST,         // https://publish-p123-e456.adobeaemcloud.com
    REACT_APP_GRAPHQL_ENDPOINT,
} = process.env;
...

// Initialize the AEM Headless client with the AEM Service host, which dictates the AEM service provides the GraphQL data.
export const aemHeadlessClient = new AEMHeadless({
    serviceURL: REACT_APP_AEM_HOST,
    endpoint: REACT_APP_GRAPHQL_ENDPOINT
});

React useEffect(…) gancio

Gli hook useEffect personalizzati di React chiamano il client headless AEM, inizializzato con l’host AEM, per conto del componente React che esegue il rendering della visualizzazione.

• src/api/persistedQueries.js

import { aemHeadlessClient , mapErrors} from "./headlessClient";
...
// The exported useEffect hook
export const getAdventureByPath = async function(adventurePath) {
    const queryVariables = {'adventurePath': adventurePath};
    return executePersistedQuery('wknd-shared/adventures-by-path', queryVariables);
}
...
// Private function that invokes the aemHeadlessClient
const executePersistedQuery = async function(persistedQueryPath, queryVariables) {
    let data;
    let errors;

    try {
        // Run the persisted query using using the aemHeadlessClient that's initialized with the AEM host
        const response = await aemHeadlessClient.runPersistedQuery(persistedQueryPath, queryVariables);
        // The GraphQL data is stored on the response's data field
        data = response.data;
        errors = response.errors ? mapErrors(response.errors) : undefined;
    } catch (e) {
        console.error(e.toJSON());
        errors = e;
    }

    return {data, errors};
}

Componente React

L'hook useEffect personalizzato, useAdventureByPath, viene importato e utilizzato per ottenere i dati tramite il client headless dell'AEM ed eseguire il rendering del contenuto per l'utente finale.

• 'src/components/AdventureDetail.js'

import { useAdventureByPath } from './api/persistedQueries';
...
// Query AEM GraphQL APIs via the useEffect hook that invokes the AEM Headless client initialized with the AEM host
let { data, error } = useAdventureByPath('/content/dam/wknd-shared/en/adventures/bali-surf-camp/adobestock-175749320.jpg')

...

Questo esempio, basato sull'esempio dell'app iOS™ headless AEM, illustra come configurare le richieste API di GraphQL AEM per connettersi a host AEM diversi in base a variabili di configurazione specifiche della build.

Le app iOS™ richiedono un client headless AEM personalizzato per interagire con le API GraphQL dell’AEM. Il client headless AEM deve essere scritto in modo che l’host del servizio AEM sia configurabile.

Configurazione della build

Il file di configurazione Xcode contiene i dettagli di configurazione predefiniti.

• Config.xcconfig

// The http/https protocol scheme used to access the AEM_HOST
AEM_SCHEME = https

// Target hostname for AEM service, do not include the scheme: http:// or https://
AEM_HOST = publish-p123-e789.adobeaemcloud.com
...

Inizializzare il client headless AEM personalizzato

L'app iOS 🔗 dell'esempio AEM headless utilizza un client AEM headless personalizzato inizializzato con i valori di configurazione per AEM_SCHEME e AEM_HOST.

...
let aemScheme: String = try Configuration.value(for: "AEM_SCHEME")  // https
let aemHost: String = try Configuration.value(for: "AEM_HOST")      // publish-p123-e456.adobeaemcloud.com

let aemHeadlessClient = Aem(scheme: aemScheme, host: aemHost);

Il client AEM headless personalizzato (api/Aem.swift) contiene un metodo makeRequest(..) che aggiunge il prefisso delle richieste API GraphQL AEM all'AEM configurato scheme e host.

• api/Aem.swift

/// #makeRequest(..)
/// Generic method for constructing and executing AEM GraphQL persisted queries
private func makeRequest(persistedQueryName: String, params: [String: String] = [:]) -> URLRequest {
    // Encode optional parameters as required by AEM
    let persistedQueryParams = params.map { (param) -> String in
        encode(string: ";\(param.key)=\(param.value)")
    }.joined(separator: "")

    // Construct the AEM GraphQL persisted query URL, including optional query params
    let url: String = "\(self.scheme)://\(self.host)/graphql/execute.json/" + persistedQueryName + persistedQueryParams;

    var request = URLRequest(url: URL(string: url)!);

    return request;
}

È possibile creare nuovi file di configurazione della build per connettersi a diversi servizi AEM. I valori specifici della build per AEM_SCHEME e AEM_HOST vengono utilizzati in base alla build selezionata in XCode, determinando la connessione del client headless AEM personalizzato con il servizio AEM corretto.

Questo esempio, basato sull'esempio dell'app AEM Headless Android™, illustra come configurare le richieste API di GraphQL AEM per connettersi a diversi servizi AEM in base a variabili di configurazione specifiche della build (o versioni).

Le app Android™ (se scritte in Java™) devono utilizzare il client AEM headless per Java™ per interagire con le API GraphQL dell'AEM. Il client AEM headless, fornito dal client AEM headless per Java™, deve essere inizializzato con l’host del servizio AEM a cui si connette.

File di configurazione della build

Le app Android™ definiscono i "productFlavors" utilizzati per creare artefatti per usi diversi.
In questo esempio viene illustrato come definire due versioni di prodotto Android™, fornendo diversi valori host del servizio AEM (AEM_HOST) per gli utilizzi di sviluppo (dev) e produzione (prod).

Nel file build.gradle dell'app, viene creato un nuovo flavorDimension denominato env.

Nella dimensione env sono definiti due productFlavors: dev e prod. Ogni productFlavor utilizza buildConfigField per impostare variabili specifiche della build che definiscono il servizio AEM a cui connettersi.

• app/build.gradle

android {
    ...
    flavorDimensions 'env'
    productFlavors {
        dev {
            dimension 'env'
            applicationIdSuffix '.dev'
            buildConfigField "String", "AEM_HOST", '"http://10.0.2.2:4503"'
            ...
        }
        prod {
            dimension 'env'
            buildConfigField "String", "AEM_HOST", '"https://publish-p123-e789.adobeaemcloud.com"'
            ...
        }
    }
    ...
}

Caricatore Android™

Inizializza il generatore AEMHeadlessClient, fornito dal client headless AEM per Java™ con il valore AEM_HOST dal campo buildConfigField.

• app/src/main/java/com/adobe/wknd/androidapp/loader/AdventuresLoader.java

public class AdventuresLoader extends AsyncTaskLoader<AdventureList> {
    ...

    @Override
    public AdventureList loadInBackground() {
        ...
        // Initialize the AEM Headless client using the AEM Host exposed via BuildConfig.AEM_HOST
        AEMHeadlessClientBuilder builder = AEMHeadlessClient.builder().endpoint(BuildConfig.AEM_HOST);
        AEMHeadlessClient client = builder.build();
        // With the AEM headless client initialized, make GraphQL persisted query calls to AEM
        ...
    }
    ...
}

Quando crei l'app Android™ per usi diversi, specifica il sapore env e viene utilizzato il valore host AEM corrispondente.

Questo esempio, basato sull'app AEM Headless React, illustra come configurare gli URL delle immagini per la connessione ai servizi AEM corretti in base alle variabili di ambiente.

In questo esempio viene illustrato il prefisso del campo di riferimento immagine _dynamicUrl, con una variabile di ambiente React configurabile REACT_APP_AEM_HOST.

File di ambiente React

React utilizza file di ambiente personalizzati, o .env file, memorizzati nella directory principale del progetto per definire valori specifici della build. Ad esempio, il file .env.development contiene i valori utilizzati per durante lo sviluppo, mentre .env.production contiene i valori utilizzati per le build di produzione.

• .env.development

# Environment variable used to specify the AEM service the React app will connect to when running under this profile
REACT_APP_AEM_HOST=https://publish-p123-e456.adobeaemcloud.com
...

È possibile specificare .env file per altri usi 🔗 tramite il postfix di .env e un descrittore semantico, ad esempio .env.stage o .env.production. È possibile utilizzare un file .env diverso durante l'esecuzione o la creazione dell'app React impostando REACT_APP_ENV prima di eseguire un comando npm.

Ad esempio, package.json di un'app React può contenere la seguente configurazione scripts:

• package.json

...
"scripts": {
  "build:development": "REACT_APP_ENV=development npm run build",
  "build:stage": "REACT_APP_ENV=stage npm run build",
  "build:production": "REACT_APP_ENV=production npm run build"
},
...

Componente React

Il componente React importa la variabile di ambiente REACT_APP_AEM_HOST e aggiunge il prefisso _dynamicUrl all'immagine per fornire un URL immagine completamente risolvibile.

La stessa variabile di ambiente REACT_APP_AEM_HOST viene utilizzata per inizializzare il client AEM headless utilizzato dall'hook useEffect personalizzato useAdventureByPath(..) utilizzato per recuperare i dati GraphQL dall'AEM. Utilizzando la stessa variabile per creare la richiesta API GraphQL dell’URL dell’immagine, assicurati che l’app React interagisca con lo stesso servizio AEM per entrambi i casi d’uso.

• 'src/components/AdventureDetail.js'

...
// Import the AEM origin from the app's environment configuration
const AEM_HOST = env.process.REACT_APP_AEM_HOST; // https://publish-p123-e456.adobeaemcloud.com

let { data, error } = useAdventureByPath('/content/dam/wknd-shared/en/adventures/bali-surf-camp/bali-surf-camp')

return (
    // Prefix the image src URL with the AEM host
    <img src={AEM_HOST + data.adventureByPath.item.primaryImage._dynamicUrl }>
    {/* Resulting in: <img src="https://publish-p123-e456.adobeaemcloud.com/adobe/dynamicmedia/deliver/dm-aid--de43411-88ec-4c4d-b5ef-e3dc4bc0cb42/adobestock-175749320.jpg"/>  */}
)

Questo esempio, basato sull'esempio dell'app AEM Headless iOS™, illustra come gli URL dell'immagine AEM possono essere configurati per connettersi a diversi host AEM in base a variabili di configurazione specifiche della build.

Configurazione della build

Il file di configurazione Xcode contiene i dettagli di configurazione predefiniti.

• Config.xcconfig

// The http/https protocol scheme used to access the AEM_HOST
AEM_SCHEME = https

// Target hostname for AEM service, do not include the scheme: http:// or https://
AEM_HOST = publish-p123-e789.adobeaemcloud.com
...

Generatore URL immagine

In Aem.swift, l'implementazione client headless AEM personalizzata, una funzione personalizzata imageUrl(..) utilizza il percorso dell'immagine fornito nel campo _dynamicUrl nella risposta GraphQL e lo precede con l'host AEM. Questa funzione viene quindi richiamata nelle visualizzazioni di iOS ogni volta che viene eseguito il rendering di un’immagine.

• WKNDAdventures/AEM/Aem.swift

class Aem: ObservableObject {
    let scheme: String
    let host: String
    ...
    init(scheme: String, host: String) {
        self.scheme = scheme
        self.host = host
    }
    ...
    /// Prefixes AEM image dynamicUrl with the AEM scheme/host
    func imageUrl(dynamicUrl: String) -> URL {
        return URL(string: "\(self.scheme)://\(self.host)\(dynamicUrl)")!
    }
    ...
}

Vista iOS

La vista iOS e il prefisso del valore dell'immagine _dynamicUrl forniscono un URL immagine completamente risolvibile.

• WKNDAdventures/Views/AdventureListItemView.swift

import SDWebImageSwiftUI
...
struct AdventureListItemView: View {
    @EnvironmentObject private var aem: Aem

    var adventure: Adventure

    var body: some View {
        HStack {
            // Path the image dynamicUrl to `aem.imageUrl(..)` to prepend the AEM service host
            AdventureRowImage(imageUrl: aem.imageUrl(dynamicUrl: adventure.image()))
            Text(adventure.title)
            Spacer()
        }
    }
}
...

È possibile creare nuovi file di configurazione della build per connettersi a diversi servizi AEM. I valori specifici della build per AEM_SCHEME e AEM_HOST vengono utilizzati in base alla build selezionata in XCode, in modo che il client headless AEM personalizzato interagisca con il servizio AEM corretto.

Questo esempio, basato sull'esempio dell'app AEM Headless Android™, illustra come gli URL dell'immagine AEM possono essere configurati per connettersi a diversi servizi AEM in base a variabili di configurazione specifiche della build (o versioni).

File di configurazione della build

Le app Android™ definiscono "productFlavors" che vengono utilizzati per creare artefatti per usi diversi.
In questo esempio viene illustrato come definire due versioni di prodotto Android™, fornendo diversi valori host del servizio AEM (AEM_HOST) per gli utilizzi di sviluppo (dev) e produzione (prod).

Nel file build.gradle dell'app, viene creato un nuovo flavorDimension denominato env.

Nella dimensione env sono definiti due productFlavors: dev e prod. Ogni productFlavor utilizza buildConfigField per impostare variabili specifiche della build che definiscono il servizio AEM a cui connettersi.

• app/build.gradle

android {
    ...
    flavorDimensions 'env'
    productFlavors {
        dev {
            dimension 'env'
            applicationIdSuffix '.dev'
            buildConfigField "String", "AEM_HOST", '"http://10.0.2.2:4503"'
            ...
        }
        prod {
            dimension 'env'
            buildConfigField "String", "AEM_HOST", '"https://publish-p123-e789.adobeaemcloud.com"'
            ...
        }
    }
    ...
}

Caricamento dell’immagine dell’AEM

Android™ utilizza ImageGetter per recuperare e memorizzare nella cache locale i dati immagine dall'AEM. In prepareDrawableFor(..) l'host del servizio AEM, definito nella configurazione di compilazione attiva, viene utilizzato per prefissare il percorso dell'immagine creando un URL risolvibile in AEM.

• app/src/main/java/com/adobe/wknd/androidapp/loader/RemoteImagesCache.java

...
public class RemoteImagesCache implements Html.ImageGetter {
    ...
    private final Map<String, Drawable> drawablesByPath = new HashMap<>();
    ...
    public void prepareDrawableFor(String path) {
        ...

        // Prefix the image path with the build config AEM_HOST variable
        String urlStr = BuildConfig.AEM_HOST + path;

        URL url = new URL(urlStr);
        HttpURLConnection connection = (HttpURLConnection) url.openConnection();
        // Get the image data from AEM
        Drawable drawable = Drawable.createFromStream(is, new File(path).getName());
        ...
        // Save the image data into the cache using the path as the key
        drawablesByPath.put(path, drawable);
        ...
    }

    @Override
    public Drawable getDrawable(String dynamicUrl) {
        // Get the image data from the cache using the dynamicUrl as the key
        return drawablesByPath.get(dynamicUrl);
    }
}

Vista Android™

La visualizzazione Android™ ottiene i dati dell'immagine tramite RemoteImagesCache utilizzando il valore _dynamicUrl della risposta di GraphQL.

• app/src/main/java/com/adobe/wknd/androidapp/AdventureDetailFragment.java

...
public class AdventureDetailFragment extends Fragment implements LoaderManager.LoaderCallbacks<Adventure> {
    ...
    private ImageView adventureDetailImage;
    ...

    private void updateContent() {
        ...
        adventureDetailImage.setImageDrawable(RemoteImagesCache.getInstance().getDrawable(adventure.getPrimaryImageDynamicUrl()));
        ...
    }
...
}

Quando crei l'app Android™ per usi diversi, specifica il sapore env e viene utilizzato il valore host AEM corrispondente.