Ajout d’attributs de commande personnalisés
Dans cet article, vous apprenez à ajouter des attributs personnalisés aux événements back-office. Avec les attributs personnalisés, vous pouvez capturer des informations riches sur les données afin d’améliorer les analyses et de créer davantage d’expériences personnalisées pour vos acheteurs.
Les attributs personnalisés sont pris en charge à deux niveaux :
- Niveau de commande
- Niveau de l’élément de commande
L’ajout d’attributs personnalisés aux événements back-office requiert que vous :
- Créez un projet dans votre installation Commerce.
- Mettez à jour votre schéma afin que les nouveaux attributs personnalisés puissent être correctement ingérés dans Experience Platform.
- Dans Admin, vérifiez que les attributs personnalisés sont capturés et envoyés à l’Experience Platform.
Etape 1 : création de la structure de répertoire
- Accédez au répertoire
app/code
de votre installation Commerce et créez un répertoire de module. Par exemple :Magento/AepCustomAttributes
. Ce répertoire contient les fichiers nécessaires à vos attributs personnalisés. - Dans le répertoire du module, créez un sous-répertoire appelé
etc
. Le répertoireetc
contient les fichiersmodule.xml
,query.xml
,di.xml
etet_schema.xml
.
Étape 2 : définir les dépendances et la version de configuration
Créez un fichier module.xml
qui définit les dépendances et la version de configuration. Par exemple :
<?xml version="1.0"?>
<!--
/**
* Copyright (c) [year], [name]. All rights reserved.
*/
-->
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">
<module name="Magento_SalesRuleStaging" setup_version="2.0.0">
<sequence>
<module name="Magento_Staging"/>
<module name="Magento_SalesRule"/>
</sequence>
</module>
</config>
Étape 3 : récupération des données de commande client
Créez un fichier query.xml
qui récupère les données de commande client. Par exemple :
<query>
<source name="sales_order" type="sales">
<attribute name="increment_id" operator="eq" alias="order_increment_id"/>
<link source="inventory_source_item" condition_type="by_sku"/>
</source>
</query>
Étape 4 : configuration de l’injection de dépendance
Créez un fichier di.xml
qui configure l’injection de dépendance. Par exemple :
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
package="com.example.instrumentedtest"
android:versionCode="1"
android:versionName="1.0">
<uses-sdk android:minSdkVersion="8" android:targetSdkVersion="15"/>
<instrumentation
android:name=".MyInstrumentationTestRunner"
android:targetPackage="com.example.instrumentedtest"/>
<!-- More instrumentation elements might be here -->
</manifest>
Étape 5 : définition des services utilisés pour l’injection de dépendance
Créez un fichier et_schema.xml
qui définit les services utilisés pour l’injection de dépendance. Par exemple :
<services>
<service id="App\Controller\MainController" class="App\Controller\MainController">
<argument type="service" id="doctrine.orm.default_entity_manager"/>
<argument type="service" id="form.factory"/>
<argument type="service" id="security.authorization_checker"/>
</service>
<!-- ... -->
<service id="App\Controller\SecurityController" class="App\Controller\SecurityController">
<argument type="service" id="security.authentication_utils"/>
<tag name="controller.service_arguments"/>
</service>
<!-- ... -->
</services>
Étape 6 : création d’un répertoire pour les fichiers PHP
Au même niveau que le répertoire etc
, créez un répertoire appelé Module/Provider
. Ce répertoire contient les fichiers PHP OrderCustomAttributes
et OrderItemCustomAttributes
.
Étape 7 : Définition des attributs OrderCustomAttributes
Créez un fichier OrderCustomAttributes.php
qui définit les attributs personnalisés de commande. Par exemple :
namespace App\Transformers;
use League\Fractal\TransformerAbstract;
use Illuminate\Support\Collection;
class CustomAttributeTransformer extends TransformerAbstract
{
protected $availableIncludes = [];
protected $defaultIncludes = [];
public function __construct($signsField, $jsonSignsField = null)
{
$this->signsField = $signsField;
$this->jsonSignsField = $jsonSignsField;
}
public function transform(Collection $collection)
{
// Initialize array for additional information.
$additionalInformation = [];
// Source - this comes from values sent to this transformer.
foreach ($collection->{$this->signsField} ?: [] as $value) {
if (is_array($value)) {
// If value is an array, serialize it.
foreach ($value as &$item) {
if (isset($item['custom_attr'])) {
// Serialize custom attribute data.
...
}
}
} else {
// Add non-array values directly.
...
}
}
...
return [
'current' => ...,
'additional_information' => ...,
'source' => ...,
];
}
private function flatten(array $values)
{
return Arr::flatten($values);
}
}
Étape 8 : définition des attributs personnalisés OrderItem
Créez un fichier OrderItemCustomAttributes.php
qui définit les attributs personnalisés de l’élément de commande. Par exemple :
namespace Magento\AepCustomAttributes\Model\Provider;
use Magento\Framework\Serialize\Serializer\Json;
class OrderItemCustomAttribute
{
private Json $jsonSerializer;
private string $usingField;
public function __construct(Json $jsonSerializer, string $usingField)
{
$this->jsonSerializer = $jsonSerializer;
$this->usingField = $usingField;
}
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) ?? [];
$attrLabel = implode(',', ['label1', 'label2']);
$unserializedData['custom_attr1'] = $attrLabel;
$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;
}
private function flatten(array $values): array
{
return array_merge([], ...array_values($values));
}
}
Étape 9 : création d’un répertoire pour le fichier productContext
Au même niveau que le répertoire etc
, créez un répertoire appelé Plugin/Module
. Ce répertoire contient le fichier ProductContext.php
.
Étape 10 : définition de la classe ProductContext
Créez un fichier appelé ProductContext.php
qui définit la classe ProductContext
. Par exemple :
namespace Magento\Catalog\Model\Product;
use Magento\Framework\App\ResourceConnection;
use Magento\Quote\Api\Data\CartInterface;
class ProductContext
{
private $brandCache = [];
private $resourceConnection;
public function __construct(
ResourceConnection $resourceConnection
) {
$this->resourceConnection = $resourceConnection;
}
public function afterGetProductData($subject, array $result)
{
if (isset($result['brand_id'])) {
if (!isset($this->brandCache[$result['brand_id']])) {
// @todo load brand label by brand id.
$this->brandCache[$result['brand_id']] = 'Brand Label ' . $result['brand_id'];
}
$result['brands'] = ['label' => $this->brandCache[$result['brand_id']]];
}
return $result;
}
}
Étape 11 : Enregistrement du module
Au même niveau que le répertoire etc
, créez un fichier registration.php
qui enregistre le module. Par exemple :
use \Magento\Framework\Component\ComponentRegistrar;
ComponentRegistrar::register(
ComponentRegistrar::MODULE,
'Dfe_Stripe',
__DIR__
);
Étape 12 : Étendre votre schéma XDM existant
Pour vous assurer que les nouveaux attributs de commande personnalisés peuvent être ingérés par votre schéma Commerce dans Experience Platform, vous devez étendre le schéma pour inclure ces champs personnalisés.
Pour savoir comment étendre un schéma XDM existant afin d’inclure ces champs personnalisés, reportez-vous à l’article Créer et modifier des schémas dans l’interface utilisateur de la documentation de l’Experience Platform. Le champ Identifiant du client est généré dynamiquement. Toutefois, la structure du champ doit ressembler à l’exemple fourni dans la documentation de l’Experience Platform.
Pour commerce.order
, ajoutez un champ pour le niveau de commande :
Pour productListItems
, ajoutez des champs au niveau de l’élément de commande :
Étape 12 : confirmer que les données sont capturées
Affichez l’onglet Personnalisation des données dans l’Admin pour confirmer que les données d’attributs personnalisés sont capturées et envoyées à l’Experience Platform.
Dépannage
Si le message No custom order attributes found.
s'affiche dans l'onglet Data Customization, vérifiez les points suivants :
- Vous avez rempli les conditions préalables pour activer l’ extension du connecteur de données.
- Vous avez configuré les attributs de commande personnalisés.
- Au moins un événement de commande a été généré.