Sviluppo con Commerce Cloud SAP

Il framework di integrazione include un livello di integrazione con un'API. Questo consente di:

• collegare un sistema eCommerce ed estrarre i dati del prodotto in AEM

• creazione di componenti AEM per funzionalità di e-commerce indipendenti dal motore eCommerce specifico

Per utilizzare il livello di integrazione sono disponibili diversi componenti AEM predefiniti. Attualmente si tratta di:

• un componente per la visualizzazione di un prodotto
• un carrello
• check-out

Per la ricerca viene fornito un gancio di integrazione che consente di utilizzare la ricerca di AEM, la ricerca del sistema eCommerce, una ricerca di terze parti (come Search&Promote) o una combinazione di esso.

Selezione motore di eCommerce

Il framework eCommerce può essere utilizzato con qualsiasi soluzione eCommerce, il motore utilizzato deve essere identificabile da AEM:

• I motori di eCommerce sono servizi OSGi che supportano l'interfaccia CommerceService

  • I motori possono essere distinti da una proprietà di servizio commerceProvider

• AEM supporta Resource.adaptTo() per CommerceService e Product

  • L'implementazione di adaptTo cerca una proprietà cq:commerceProvider nella gerarchia della risorsa:

    • Se trovato, il valore viene utilizzato per filtrare la ricerca del servizio commerce.

    • Se non viene trovato, viene utilizzato il servizio di commercio di livello più elevato.

  • Viene utilizzato un mixin cq:Commerce per aggiungere il cq:commerceProvider alle risorse fortemente tipizzate.

• La proprietà cq:commerceProvider viene utilizzata anche per fare riferimento alla definizione di commerce factory appropriata.

  • Ad esempio, una proprietà cq:commerceProvider con il valore hybris sarà correlata alla configurazione OSGi per Day CQ Commerce Factory for Hybris (com.adobe.cq.commerce.hybris.impl.HybrisServiceFactory) - dove il parametro commerceProvider ha anche il valore hybris.

  • Qui è possibile configurare ulteriori proprietà, ad esempio Versione catalogo (se appropriato e disponibile).

Vedere gli esempi seguenti:

cq:commerceProvider = geometrixx	in un’installazione AEM standard è necessaria un’implementazione specifica; ad esempio, l'esempio geometrixx, che include estensioni minime per l'API generica
cq:commerceProvider = hybris	implementazione di hybris

Esempio

/content/store
+ cq:commerceProvider = hybris
  + mens
    + polo-shirt-1
    + polo-shirt-2
    + employee
+ cq:commerceProvider = jcr
  + adobe-logo-shirt
    + cq:commerceType = product
    + price = 12.50
  + adobe-logo-shirt_S
    + cq:commerceType = variant
    + size = S
  + adobe-logo-shirt_XL
    + cq:commerceType = variant
    + size = XL
    + price = 14.50

Sviluppo per hybris 4

L'estensione hybris di eCommerce Integration Framework è stata aggiornata per supportare Hybris 5, mantenendo al contempo la compatibilità con Hybris 4.

Le impostazioni predefinite nel codice sono sintonizzate per Hybris 5.

Per sviluppare per Hybris 4 è necessario quanto segue:

• Quando si richiama l'area di visualizzazione, aggiungere al comando il seguente argomento della riga di comando

  -P hybris4

  Scarica la distribuzione preconfigurata di Hybris 4 e la incorpora nel bundle cq-commerce-hybris-server.

• In Gestione configurazione OSGi:

  • Disattivate il supporto di Hybris 5 per il servizio Parser di risposte predefinito.

  • Verificate che il servizio Gestore autenticazione di base Hybris abbia una classificazione di servizio inferiore a quella del servizio Gestore OAuth di Hybris.

Gestione sessione

hybris utilizza una sessione utente per memorizzare informazioni come il carrello acquisti del cliente. L'ID sessione viene restituito da hybris in un cookie JSESSIONID che deve essere inviato in seguito a richieste successive a hybris. Per evitare di memorizzare l’ID sessione nell’archivio, questo viene codificato in un altro cookie memorizzato nel browser dell’acquirente. Vengono eseguiti i seguenti passaggi:

• Alla prima richiesta non viene impostato alcun cookie sulla richiesta dell'acquirente; viene quindi inviata una richiesta all’istanza hybris per creare una sessione.

• I cookie di sessione vengono estratti dalla risposta, codificati in un nuovo cookie (ad esempio, hybris-session-rest) e impostati sulla risposta dell'acquirente. La codifica in un nuovo cookie è necessaria, perché il cookie originale è valido solo per un determinato percorso e in caso contrario non viene inviato dal browser nelle richieste successive. Le informazioni sul percorso devono essere aggiunte anche al valore del cookie.

• Su richieste successive, i cookie vengono decodificati dai cookie hybris-session-<*xxx*> e impostati sul client HTTP utilizzato per richiedere i dati da hybris.

CommerceSession

• Questa sessione "possiede" il carrello

  • esegue add/remove/etc

  • esegue i vari calcoli sul carrello;

    commerceSession.getProductPrice(Product product)

• Possiede la posizione di storage per i dati order

  CommerceSession.getUserContext()

• Possiede anche la connessione di elaborazione pagamento

• Possiede anche la connessione fulfillment

Sincronizzazione dei prodotti e pubblicazione

I dati di prodotto mantenuti in hybris devono essere disponibili in AEM. È stato attuato il seguente meccanismo:

• Un carico iniziale di ID è fornito da hybris come feed. Possono essere presenti aggiornamenti a questo feed.
• hybris fornirà informazioni di aggiornamento tramite un feed (che AEM sondaggi).
• Quando AEM utilizza i dati del prodotto, invierà le richieste ai hybris per i dati correnti (richiesta di ricezione condizionale utilizzando l'ultima data modificata).
• In hybris è possibile specificare il contenuto di feed in modo dichiarativo.
• La mappatura della struttura del feed al modello di contenuto AEM avviene nella scheda di feed sul lato AEM.

• L’importazione (b) viene utilizzata per l’impostazione iniziale della struttura ad albero della pagina in AEM per i cataloghi.

• Le modifiche al catalogo negli ibridi sono indicate per AEM tramite un feed, che poi si propagano a AEM (b)

  • Prodotto aggiunto/eliminato/modificato rispetto alla versione del catalogo.

  • Prodotto approvato.

• L'estensione hybris fornisce un importatore polling ("schema hybris"), che può essere configurato per importare modifiche in AEM a un intervallo specificato (ad esempio, ogni 24 ore in cui l'intervallo è specificato in secondi):

      http://localhost:4502/content/geometrixx-outdoors/en_US/jcr:content.json
       {
       * "jcr:mixinTypes": ["cq:PollConfig"],
       * "enabled": true,
       * "source": "hybris:outdoors",
       * "jcr:primaryType": "cq:PageContent",
       * "interval": 86400
       }
  

• La configurazione del catalogo in AEM riconosce le versioni del catalogo In fase e Online.

• La sincronizzazione di prodotti tra versioni catalogo richiederà una (disattivazione)attivazione della pagina AEM corrispondente (a, c)

  • L'aggiunta di un prodotto a una versione di catalogo Online richiede l'attivazione della pagina del prodotto.

  • La rimozione di un prodotto richiede la disattivazione.

• L'attivazione di una pagina in AEM c) richiede un controllo (b) ed è possibile solo se

  • Il prodotto è in una versione di catalogo Online per le pagine di prodotto.

  • I prodotti di riferimento sono disponibili in una versione di catalogo Online per altre pagine (ad esempio, pagine di campagna).

• Le pagine di prodotto attivate devono accedere alla versione online dei dati del prodotto (d).

• L’istanza di pubblicazione AEM richiede l’accesso agli hybris per il recupero di prodotti e dati personalizzati (d).

Architettura

Architettura del prodotto e delle varianti

Un singolo prodotto può presentare più varianti; ad esempio, può variare in base al colore e/o alla dimensione. Un prodotto deve definire quali proprietà determinano la variazione; vengono denominati questi assi varianti.

Tuttavia, non tutte le proprietà sono assi variabili. Le variazioni possono interessare anche altre proprietà; ad esempio, il prezzo potrebbe dipendere dalle dimensioni. Queste proprietà non possono essere selezionate dall'acquirente e pertanto non sono considerate assi di variante.

Ciascun prodotto e/o variante è rappresentato da una risorsa e pertanto viene mappato 1:1 su un nodo del repository. È un corollario che un prodotto e/o una variante specifica possa essere identificato in modo univoco dal suo percorso.

La risorsa prodotto/variante non contiene sempre i dati effettivi del prodotto. Può trattarsi di una rappresentazione dei dati effettivamente contenuti in un altro sistema (ad esempio gli ibridi). Ad esempio, le descrizioni dei prodotti, i prezzi, ecc. non vengono memorizzati in AEM, ma recuperati in tempo reale dal motore eCommerce.

Qualsiasi risorsa prodotto può essere rappresentata da un Product API. La maggior parte delle chiamate nell'API del prodotto sono specifiche per le varianti (anche se le variazioni possono ereditare valori condivisi da un predecessore), ma ci sono anche chiamate che elencano il set di varianti ( getVariantAxes(), getVariants(), ecc.).

Riferimenti prodotto e dati prodotto

In generale:

• i dati del prodotto si trovano in /etc

• e i riferimenti ai prodotti in /content.

Deve essere presente una mappa 1:1 tra le varianti di prodotto e i nodi dati del prodotto.

Anche i riferimenti ai prodotti devono avere un nodo per ogni variante presentata, ma non è necessario presentare tutte le varianti. Ad esempio, se un prodotto ha varianti S, M, L, i dati del prodotto potrebbero essere:

etc
|──commerce
|  |──products
|     |──shirt
|       |──shirt-s
|       |──shirt-m
|       |──shirt-l

Mentre un catalogo "Big and Tall" può contenere solo:

content
|──big-and-tall
|  |──shirt
|     |──shirt-l

Infine, non è previsto l'uso di dati di prodotto. È possibile inserire tutti i dati di prodotto sotto i riferimenti nel catalogo; ma non è possibile avere più cataloghi senza duplicare tutti i dati del prodotto.

API

com.adobe.cq.comCommerce.api.Interfaccia prodotto

public interface Product extends Adaptable {

    public String getPath();            // path to specific variation
    public String getPagePath();        // path to presentation page for all variations
    public String getSKU();             // unique ID of specific variation

    public String getTitle();           // shortcut to getProperty(TITLE)
    public String getDescription();     // shortcut to getProperty(DESCRIPTION)
    public String getImageUrl();        // shortcut to getProperty(IMAGE_URL)
    public String getThumbnailUrl();    // shortcut to getProperty(THUMBNAIL_URL)

    public <T> T getProperty(String name, Class<T> type);

    public Iterator<String> getVariantAxes();
    public boolean axisIsVariant(String axis);
    public Iterator<Product> getVariants(VariantFilter filter) throws CommerceException;
}

com.adobe.cq.commerce.api.VariantFilter

/**
 * Interface for filtering variants and AxisFilter provided as common implementation
 *
 * The <code>VariantFilter</code> is used to filter variants,
 * e.g. when using {@link Product#getVariants(VariantFilter filter)}.
 */
public interface VariantFilter {
    public boolean includes(Product product);
}

/**
 * A {@link VariantFilter} for filtering variants by the given
 * axis and value. The following example returns a list of
 * variant products that have a value of <i>blue</i> on the
 * <i>color</i> axis.
 *
 * <p>
 * <code>product.getVariants(new AxisFilter("color", "blue"));</code>
 */
public class AxisFilter implements VariantFilter {

    private String axis;
    private String value;

    public AxisFilter(String axis, String value) {
        this.axis = axis;
        this.value = value;
    }

    /**
     * {@inheritDoc}
     */
    public boolean includes(Product product) {
        ValueMap values = product.adaptTo(ValueMap.class);

        if(values != null) {
            String v = values.get(axis, String.class);

            return v != null && v == value;
        }

        return false;
    }
}

• Meccanismo di storage generale

  • I nodi di prodotto sono nt:unstructured.

  • Un nodo prodotto può essere:

    • Un riferimento, con i dati del prodotto memorizzati altrove:

      • I riferimenti ai prodotti contengono una proprietà productData che fa riferimento ai dati del prodotto (in genere in /etc/commerce/products).

      • I dati del prodotto sono gerarchici; gli attributi del prodotto vengono ereditati dagli predecessori di un nodo di dati di prodotto.

      • I riferimenti ai prodotti possono anche contenere proprietà locali, che ignorano quelle specificate nei relativi dati di prodotto.

    • Un prodotto:

      • Senza una proprietà productData.

      • Un nodo di prodotto che contiene tutte le proprietà localmente (e non contiene una proprietà productData) eredita gli attributi di prodotto direttamente dai propri predecessori.

• Struttura AEM prodotto generica

  • Ogni variante deve avere un proprio nodo foglia.

  • L'interfaccia del prodotto rappresenta sia prodotti che varianti, ma il nodo del repository correlato è specifico sul quale si trova.

  • Il nodo product descrive gli attributi del prodotto e gli assi delle varianti.

Esempio

+ banyan_shirt
    - cq:commerceType = product
    - cq:productAttributes = [jcr:title, jcr:description, size, price, color]
    - cq:productVariantAxes = [color, size]
    - jcr:title = Banyan Shirt
    - jcr:description = Flowery, all-cotton shirt.
    - price = 14.00
    + banyan_shirt_s
        - cq:commerceType = variant
        - size = S
        + banyan_shirt_s_red
            - cq:commerceType = variant
            - color = red
        + banyan_shirt_s_blue
            - cq:commerceType = variant
            - color = blue
    + banyan_shirt_m
        - cq:commerceType = variant
        - size = M
        + banyan_shirt_m_red
            - cq:commerceType = variant
            - color = red
        + banyan_shirt_m_blue
            - cq:commerceType = variant
            - color = blue
    + banyan_shirt_l
        - cq:commerceType = variant
        - size = L
        + banyan_shirt_l_red
            - cq:commerceType = variant
            - color = red
        + banyan_shirt_l_blue
            - cq:commerceType = variant
            - color = blue
    + banyan_shirt_xl
        - cq:commerceType = variant
        - size = XL
        - price = 18.00

Architettura del carrello

Componenti

• Il carrello è di proprietà di CommerceSession:

  • CommerceSession esegue add/remove/etc.
  • Il CommerceSession esegue anche i vari calcoli sul carrello. "

• Anche se non direttamente collegato al carrello, il CommerceSession deve anche fornire informazioni sui prezzi del catalogo (dal momento che possiede i prezzi)

  • La determinazione prezzi può avere diversi modificatori:

    • Sconti sulla quantità.
    • Valute diverse.
    • IVA e IVA.

  • I modificatori sono completamente aperti con la seguente interfaccia:

    • int CommerceSession.getQuantityBreakpoints(Product product)
    • String CommerceSession.getProductPrice(Product product)

Archiviazione

• Archiviazione

  • Nel caso hybris, il server hybris possiede il carrello.
  • Nel caso AEM-generico i carrelli di maiuscole e minuscole sono memorizzati nel ClientContext.

Personalizzazione

• La personalizzazione deve sempre essere guidata dal ClientContext.

• Viene creato un ClientContext /version/ del carrello in tutti i casi:

  • I prodotti devono essere aggiunti utilizzando il metodo CommerceSession.addCartEntry().

• Esempio di informazioni sul carrello nel carrello dei ClientContext:

Architettura del Checkout

Dati carrello e ordine

Il CommerceSession possiede tre elementi:

1. Contenuto del carrello

2. Prezzi

3. Dettagli ordine

4. Contenuto del carrello

   Lo schema del contenuto del carrello è fisso dall'API:

   public void addCartEntry(Product product, int quantity);
   public void modifyCartEntry(int entryNumber, int quantity);
   public void deleteCartEntry(int entryNumber);
   

5. Prezzi

   Lo schema tariffario è anche fissato dall'API:

   public String getCartPreTaxPrice();
   public String getCartTax();
   public String getCartTotalPrice();
   public String getOrderShipping();
   public String getOrderTotalTax();
   public String getOrderTotalPrice();
   

6. Dettagli ordine

   Tuttavia, i dettagli dell'ordine sono non corretti dall'API:

   public void updateOrderDetails(Map<String, String> orderDetails);
   public Map<String, String> getOrderDetails();
   public void submitOrder();
   

Calcoli di spedizione

• I moduli di ordine spesso devono presentare più opzioni di spedizione (e prezzi).

• I prezzi possono essere basati su articoli e dettagli dell'ordine, come peso e/o indirizzo di consegna.

• Il CommerceSession ha accesso a tutte le dipendenze, in modo che possa essere trattato in modo simile al prezzo del prodotto:

  • La CommerceSession possiede i prezzi di spedizione.
  • Può recuperare/aggiornare i dettagli di consegna utilizzando updateOrder(Map<String, Object> delta)

Elaborazione pagamenti

• La CommerceSession possiede anche la connessione di elaborazione del pagamento.

• Gli implementatori devono aggiungere chiamate specifiche (al servizio di elaborazione dei pagamenti prescelto) all'implementazione CommerceSession.

Evasione ordine

• La CommerceSession possiede anche la connessione di evasione.
• Gli implementatori dovranno aggiungere chiamate specifiche (al servizio di elaborazione dei pagamenti prescelto) all'implementazione CommerceSession.

Definizione di ricerca

In base al modello di API per i servizi standard, il progetto eCommerce fornisce un set di API relative alla ricerca che possono essere implementate dai singoli motori di commercio.

Il progetto eCommerce contiene un componente di ricerca predefinito, che si trova in:

/libs/commerce/components/search

In questo modo si utilizza l'API di ricerca per eseguire una query sul motore di eCommerce selezionato (vedere Selezione motore di eCommerce):

API di ricerca

Il progetto principale offre diverse classi generiche / helper:

1. CommerceQuery

   Viene utilizzato per descrivere una query di ricerca (contiene informazioni sul testo della query, la pagina corrente, la dimensione della pagina, l’ordinamento e i facet selezionati). Tutti i servizi eCommerce che implementano l'API di ricerca riceveranno le istanze di questa classe per eseguire la ricerca. È possibile creare un'istanza CommerceQuery da un oggetto di richiesta ( HttpServletRequest).

2. FacetParamHelper

   Classe di utilità che fornisce un metodo statico - toParams - utilizzato per generare stringhe di parametri GET da un elenco di facet e un valore attivato. Questa funzione è utile nell’interfaccia utente, dove è necessario visualizzare un collegamento ipertestuale per ciascun valore di ciascun facet, in modo che quando l’utente fa clic sul collegamento ipertestuale il relativo valore venga attivato (ovvero se è stato selezionato, viene rimosso dalla query, altrimenti aggiunto). Questo si occupa di tutte le logiche di gestione di facet multivalore/monomalore, valori prevalenti, ecc.

Il punto di ingresso per l'API di ricerca è il metodo CommerceService#search che restituisce un oggetto CommerceResult. Per ulteriori informazioni su questo argomento, vedere la Documentazione API.

Integrazione utente

L'integrazione viene fornita tra AEM e vari sistemi di eCommerce. Ciò richiede una strategia per la sincronizzazione degli acquirenti tra i vari sistemi, in modo che il codice AEM specifico debba conoscere solo AEM e viceversa:

• Autenticazione

  Si presume che AEM sia il front-end Web only e pertanto esegue l'autenticazione all.

• Account in Hybris

  AEM un account corrispondente (subordinato) in hybris per ogni acquirente. Il nome utente di questo account è lo stesso del nome utente AEM. Una password crittografata casuale viene generata automaticamente e memorizzata (cifrata) in AEM.

Utenti preesistenti

Un front-end AEM può essere posizionato davanti a un'implementazione ibrida esistente. È inoltre possibile aggiungere un motore ibrido a un'installazione AEM esistente. A tal fine, i sistemi devono essere in grado di gestire correttamente gli utenti esistenti in entrambi i sistemi:

• AEM -> hybris

  • Quando si effettua l'accesso agli ibridi, se l'utente AEM non esiste già:

    • creare un nuovo utente hybris con una password crittografata casuale
    • memorizzare il nome utente hybris nella directory utente dell'utente AEM

  • Consulta: com.adobe.cq.commerce.hybris.impl.HybrisSessionImpl#login()

• hybris -> AEM

  • Durante l'accesso a AEM, se il sistema riconosce l'utente:

    • tentativo di accedere a hybris con nome utente/pwd fornito
    • in caso di esito positivo, create il nuovo utente in AEM con la stessa password (il valore di sale AEM specifico darà luogo a un hash AEM specifico)

  • L'algoritmo di cui sopra è implementato in un Sling AuthenticationInfoPostProcessor

    • Consulta: com.adobe.cq.commerce.hybris.impl.user.LazyUserImporter.java

Personalizzazione del processo di importazione

Per sfruttare le funzionalità esistenti del gestore di importazioni personalizzato:

• deve implementare l'interfaccia ImportHandler

• può estendere la DefaultImportHandler.

/**
 * Services implementing the <code>ImportHandler</code> interface are
 * called by the {@link HybrisImporter} to create actual commerce entities
 * such as products.
 */
public interface ImportHandler {

  /**
  * Not used.
  */
  public void createTaxonomie(ImporterContext ctx);

  /**
  * Creates a catalog with the given name.
  * @param ctx   The importer context
  * @param name  The catalog's name
  * @return Path of created catalog
  */
  public String createCatalog(ImporterContext ctx, String name) throws Exception;

  /**
  * Creates a product from the given values.
  * @param ctx                The importer context
  * @param values             The product's properties
  * @param parentCategoryPath The containing category's path
  * @return Path of created product
  */
  public String createProduct(ImporterContext ctx, ValueMap values, String parentCategoryPath) throws Exception;

  /**
  * Creates a variant product from the given values.
  * @param ctx             The importer context
  * @param values          The product's properties
  * @param baseProductPath The base product's path
  * @return Path of created product
  */
  public String createVariantProduct(ImporterContext ctx, ValueMap values, String baseProductPath) throws Exception;

  /**
  * Creates an asset for a product. This is usually a product
  * image.
  * @param ctx             The importer context
  * @param values          The product's properties
  * @param baseProductPath The product's path
  * @return Path of created asset
  */
  public String createAsset(ImporterContext ctx, ValueMap values, String productPath) throws Exception;

  /**
  * Creates a category from the given values.
  * @param ctx           The importer context
  * @param values        The category's properties
  * @param parentPath    Path of parent category or base path of import in case of root category
  * @return Path of created category
  */
  public String createCategory(ImporterContext ctx, ValueMap values, String parentCategoryPath) throws Exception;
}

Affinché il gestore personalizzato venga riconosciuto dall'importatore, deve specificare la proprietà service.rankingcon un valore superiore a 0; ad esempio.

@Component
@Service
@Property(name = "service.ranking", value = 100)
public class MyImportHandler extends DefaultImportHandler
{
...
}