Il framework eCommerce può essere utilizzato con qualsiasi soluzione eCommerce. Alcuni esempi e specifiche trattati in questo documento fanno riferimento alla soluzione hybris.
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
È disponibile anche la documentazione API.
Per utilizzare il livello di integrazione sono disponibili diversi componenti AEM predefiniti. Attualmente si tratta di:
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.
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
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 |
/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
Utilizzando CRXDE Lite potete vedere come questo viene gestito nel componente prodotto per l’implementazione di hybris:
/apps/geometrixx-outdoors/components/hybris/product/product.jsp
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.
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.
Viene creata una nuova sessione anonima quando la sessione originale non è più valida.
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
I dati di prodotto mantenuti in hybris devono essere disponibili in AEM. È stato attuato il seguente meccanismo:
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).
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.).
In effetti, gli assi di una variante sono determinati da qualsiasi valore restituito da Product.getVariantAxes()
:
Mentre i prodotti (in generale) possono avere molti assi di variante, il componente prodotto out-of-the-box gestisce solo due:
size
più uno
Questa variante aggiuntiva viene selezionata tramite la proprietà variationAxis
del riferimento prodotto (in genere color
per Geometrixx Outdoors).
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
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;
}
/**
* 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.
+ 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
Componenti
Il carrello è di proprietà di CommerceSession:
CommerceSession
esegue add/remove/etc.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:
I modificatori sono completamente aperti con la seguente interfaccia:
int CommerceSession.getQuantityBreakpoints(Product product)
String CommerceSession.getProductPrice(Product product)
Archiviazione
Archiviazione
Personalizzazione
La personalizzazione deve sempre essere guidata dal ClientContext.
Viene creato un ClientContext /version/
del carrello in tutti i casi:
CommerceSession.addCartEntry()
.Esempio di informazioni sul carrello nel carrello dei ClientContext:
Dati carrello e ordine
Il CommerceSession
possiede tre elementi:
Contenuto del carrello
Prezzi
Dettagli ordine
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);
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();
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:
CommerceSession
possiede i prezzi di spedizione.updateOrder(Map<String, Object> delta)
È possibile implementare un selettore di spedizione; ad esempio:
yourProject/commerce/components/shippingpicker
:
Essenzialmente potrebbe trattarsi di una copia di foundation/components/form/radio
, ma con callback al CommerceSession
per:
Verifica della disponibilità del metodo
Aggiunta di informazioni sui prezzi
Per consentire agli acquirenti di aggiornare la pagina dell'ordine in AEM (incluso il superset di metodi di spedizione e il testo che li descrive), pur mantenendo il controllo per esporre le relative informazioni CommerceSession
.
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
CommerceSession
possiede anche la connessione di evasione.CommerceSession
.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.
Attualmente, solo il motore ibrido implementa l'API di ricerca out-of-the-box.
Tuttavia, l'API di ricerca è generica e può essere implementata da ogni CommerceService singolarmente.
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):
Il progetto principale offre diverse classi generiche / helper:
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
).
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.
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.
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à:
Consulta: com.adobe.cq.commerce.hybris.impl.HybrisSessionImpl#login()
hybris -> AEM
Durante l'accesso a AEM, se il sistema riconosce l'utente:
L'algoritmo di cui sopra è implementato in un Sling AuthenticationInfoPostProcessor
com.adobe.cq.commerce.hybris.impl.user.LazyUserImporter.java
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.ranking
con un valore superiore a 0; ad esempio.
@Component
@Service
@Property(name = "service.ranking", value = 100)
public class MyImportHandler extends DefaultImportHandler
{
...
}