Aggiungi attributi ordine personalizzati
- Argomenti:
- Personalizzazione
Creato per:
- Amministratore
- Sviluppatore
In questo articolo imparerai ad aggiungere attributi personalizzati agli eventi di back office. Con gli attributi personalizzati, puoi acquisire informazioni approfondite su dati avanzati per migliorare l’analisi e creare ulteriori esperienze personalizzate per gli acquirenti.
Gli attributi personalizzati sono supportati a due livelli:
- Livello dell’ordine
- Livello articolo ordine
Per aggiungere attributi personalizzati agli eventi di back office è necessario:
- Crea un progetto nell'installazione di Commerce.
- Aggiorna lo schema in modo che i nuovi attributi personalizzati possano essere correttamente acquisiti in Experience Platform.
- In Admin, verifica che gli attributi personalizzati vengano acquisiti e inviati ad Experience Platform.
Passaggio 1: creare la struttura della directory
- Passare alla directory
app/code
nell'installazione di Commerce e creare una directory di moduli. Esempio:Magento/AepCustomAttributes
. Questa directory contiene i file necessari per gli attributi personalizzati. - Nella directory del modulo, creare una sottodirectory denominata
etc
. La directoryetc
contiene i filemodule.xml
,query.xml
,di.xml
eet_schema.xml
.
Passaggio 2: definire le dipendenze e la versione di impostazione
Creare un file module.xml
che definisce le dipendenze e la versione di installazione. Ad esempio:
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">
<module name="Magento_AepCustomAttributes">
<sequence>
<module name="Magento_SalesOrderDataExporter"/>
</sequence>
</module>
</config>
Passaggio 3: Recuperare i dati dell'ordine cliente
Creare un file query.xml
che recupera i dati dell'ordine cliente. Ad esempio:
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:Module:Magento_QueryXml:etc/query.xsd">
<query name="salesOrdersV2">
<source name="sales_order">
<link-source name="sales_order_inventory_source" link-type="inner">
<attribute name="inventory_source_code" alias="inventory_source" />
<using glue="and">
<condition attribute="order_id" operator="eq" type="identifier">entity_id</condition>
</using>
</link-source>
</source>
</query>
</config>
Passaggio 4: impostare l’iniezione di dipendenza
Creare un file di.xml
che configura l'iniezione di dipendenza. Ad esempio:
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
<type name="Magento\AepCustomAttributes\Model\Provider\CustomAttribute">
<arguments>
<argument name="usingField" xsi:type="string">commerceOrderId</argument>
</arguments>
</type>
<type name="Magento\AepCustomAttributes\Model\Provider\OrderItemCustomAttribute">
<arguments>
<argument name="usingField" xsi:type="string">entityId</argument>
</arguments>
</type>
<type name="Magento\DataServices\Model\ProductContext">
<plugin name="product-context-plugin" type="Magento\AepCustomAttributes\Plugin\Model\ProductContext"/>
</type>
</config>
Passaggio 5: definire i servizi utilizzati per l’iniezione della dipendenza
Creare un file et_schema.xml
che definisce i servizi utilizzati per l'iniezione di dipendenza. Ad esempio:
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_DataExporter:etc/et_schema.xsd">
<record name="OrderV2">
<field name="additionalInformation" type="CustomAttribute" repeated="true" provider="Magento\AepCustomAttributes\Model\Provider\CustomAttribute">
<using field="commerceOrderId"/>
</field>
</record>
<record name="OrderItemV2">
<field name="additionalInformation" type="CustomAttribute" repeated="true" provider="Magento\AepCustomAttributes\Model\Provider\OrderItemCustomAttribute">
<using field="entityId"/>
</field>
</record>
</config>
Passaggio 6: creare una directory per i file PHP
Allo stesso livello della directory etc
, creare una directory denominata Module/Provider
. Questa directory contiene i file PHP OrderCustomAttributes
e OrderItemCustomAttributes
.
Passaggio 7: definire OrderCustomAttributes
Creare un file OrderCustomAttributes.php
che definisce gli attributi personalizzati dell'ordine. Ad esempio:
declare(strict_types=1);
namespace Magento\AepCustomAttributes\Model\Provider;
use Magento\Framework\Serialize\Serializer\Json;
class CustomAttribute
{
/**
* @var Json
*/
private Json $jsonSerializer;
/**
* @var string
*/
private string $usingField = '';
/**
* @param string $usingField
* @param Json $jsonSerializer
*/
public function __construct(
string $usingField,
Json $jsonSerializer
) {
$this->usingField = $usingField;
$this->jsonSerializer = $jsonSerializer;
}
/**
* @param array $values
* @return array
*/
public function get(array $values): array
{
$output = [];
/**
* Entity IDs
*/
$ids = array_column($values, $this->usingField);
foreach ($this->flatten($values) as $row) {
$info = \is_string($row['additionalInformation']) ? $row['additionalInformation'] : '{}';
$unserializedData = $this->jsonSerializer->unserialize($info) ?? [];
if (isset($row)) {
$unserializedData['order_channel'] = 'order_channel';
$unserializedData['order_status'] = 'order_status';
$additionalInformation = [];
foreach ($unserializedData as $name => $value) {
$additionalInformation[] = [
'name' => $name,
'value' => \is_string($value) ? $value : $this->jsonSerializer->serialize($value)
];
}
foreach ($additionalInformation as $information) {
$output[] = [
'additionalInformation' => $information,
$this->usingField => $row[$this->usingField],
];
}
}
}
return $output;
}
/**
* @param $values
* @return array
*/
private function flatten($values): array
{
if (isset(current($values)[0])) {
return array_merge([], ...array_values($values));
}
return $values;
}
}
Passaggio 8: definire OrderItemCustomAttributes
Creare un file OrderItemCustomAttributes.php
che definisce gli attributi personalizzati dell'elemento dell'ordine. Ad esempio:
declare(strict_types=1);
namespace Magento\AepCustomAttributes\Model\Provider;
use Magento\Framework\Serialize\Serializer\Json;
class OrderItemCustomAttribute
{
/**
* @var Json
*/
private Json $jsonSerializer;
/**
* @var string
*/
private string $usingField = '';
/**
* @param Json $jsonSerializer
* @param string $usingField
*/
public function __construct(
Json $jsonSerializer,
string $usingField
) {
$this->jsonSerializer = $jsonSerializer;
$this->usingField = $usingField;
}
/**
* Getting additional attributes data.
*
* @param array $values
* @return array
*/
public function get(array $values): array
{
$output = [];
$values = $this->flatten($values);
foreach ($values as $row) {
$info = \is_string($row['additionalInformation']) ? $row['additionalInformation'] : '{}';
$unserializedData = $this->jsonSerializer->unserialize($info) ?? [];
$unserializedData['product_brand'] = implode(',', ['label 1', 'label 2']);
$additionalInformation = [];
foreach ($unserializedData as $name => $value) {
$additionalInformation[] = [
'name' => $name,
'value' => \is_string($value) ? $value : $this->jsonSerializer->serialize($value)
];
}
foreach ($additionalInformation as $information) {
$output[] = [
'additionalInformation' => $information,
$this->usingField => $row[$this->usingField],
];
}
}
return $output;
}
/**
* @param $values
* @return array
*/
private function flatten($values): array
{
if (isset(current($values)[0])) {
return array_merge([], ...array_values($values));
}
return $values;
}
}
Passaggio 9: creare una directory per il file productContext
Allo stesso livello della directory etc
, creare una directory denominata Plugin/Module
. Questa directory contiene il file ProductContext.php
.
Passaggio 10: definire la classe ProductContext
Creare un file denominato ProductContext.php
che definisce la classe ProductContext
. Ad esempio:
<?php>
namespace Magento\AepCustomAttributes\Plugin\Model;
use Magento\Catalog\Model\Product;
use Magento\DataServices\Model\ProductContext as Subject;
use Magento\Framework\App\ResourceConnection;
class ProductContext
{
private ?array $brandCache = [];
public function __construct(
private ResourceConnection $resourceConnection ) {
}
public function afterGetContextData(Subject $subject, array $result Product $product)
{
$brand = $product->getCustomAttribute('cust_attr1');
if (!empty($brand) && $brand->getValue()) {
$result['brands'] = ['brand_label_1', 'brand_label_2'];
}
return $result;
}
}
Passaggio 11: registrare il modulo
Allo stesso livello della directory etc
, creare un file registration.php
che registri il modulo. Ad esempio:
<?php>
declare(strict_types=1);
use \Magento\Framework\Component\ComponentRegistrar;
ComponentRegistrar::register(
ComponentRegistrar::MODULE,
'Magento_AepCustomAttributes',
__DIR__
);
Passaggio 12: estendere lo schema XDM esistente
Per garantire che i nuovi attributi dell'ordine personalizzato possano essere acquisiti dallo schema Commerce in Experience Platform, è necessario estendere lo schema per includere questi campi personalizzati.
Per informazioni su come estendere uno schema XDM esistente per includere questi campi personalizzati, consulta l'articolo Creare e modificare gli schemi nell'interfaccia utente nella documentazione di Experience Platform. Il campo ID tenant viene generato in modo dinamico; tuttavia, la struttura del campo deve essere simile all’esempio fornito nella documentazione di Experience Platform.
A commerce.order
, aggiungere un campo per il livello Ordine:
A productListItems
, aggiungere i campi per il livello di elemento dell'ordine:
Passaggio 12: verifica che i dati vengano acquisiti
Visualizza la scheda Personalizzazione dati nell'amministratore per verificare che i dati degli attributi personalizzati vengano acquisiti e inviati ad Experience Platform.
Risoluzione dei problemi
Se viene visualizzato il messaggio No custom order attributes found.
nella scheda Data Customization, confermare quanto segue:
- Sono stati completati i prerequisiti per abilitare l'estensione Data Connector.
- Hai configurato attributi ordine personalizzati.
- È stato generato almeno un evento ordine.