新增自訂訂單屬性
在本文中,您將瞭解如何新增自訂屬性至後台事件。 透過自訂屬性,您可以擷取豐富的資料深入解析來增強分析,並進一步為購物者建立個人化體驗。
自訂屬性支援兩個層級:
- 訂單層級
- 訂單料號層次
將自訂屬性新增至後端辦公室事件需要您:
- 在您的Commerce安裝中建立專案。
- 更新您的結構描述,以便新的自訂屬性可以正確地內嵌到Experience Platform中。
- 在Admin中,確認正在擷取自訂屬性並傳送給Experience Platform。
步驟1:建立目錄結構
- 導覽至Commerce安裝中的
app/code
目錄,並建立模組目錄。 例如:Magento/AepCustomAttributes
。 此目錄包含自訂屬性所需的檔案。 - 在模組目錄中,建立名為
etc
的子目錄。etc
目錄包含module.xml
、query.xml
、di.xml
和et_schema.xml
檔案。
步驟2:定義相依性和設定版本
建立定義相依性和安裝程式版本的module.xml
檔案。 例如:
<?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>
步驟3:擷取銷售訂單資料
建立可擷取銷售訂單資料的query.xml
檔案。 例如:
<?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>
步驟4:設定相依性插入
建立設定相依性插入的di.xml
檔案。 例如:
<?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>
步驟5:定義用於相依性插入的服務
建立et_schema.xml
檔案,定義用於相依性插入的服務。 例如:
<?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>
步驟6:建立PHP檔案的目錄
在與etc
目錄相同的層級,建立名為Module/Provider
的目錄。 此目錄包含OrderCustomAttributes
和OrderItemCustomAttributes
PHP檔案。
步驟7:定義OrderCustomAttribute
建立定義順序自訂屬性的OrderCustomAttributes.php
檔案。 例如:
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;
}
}
步驟8:定義OrderItemCustomAttribute
建立定義訂單專案自訂屬性的OrderItemCustomAttributes.php
檔案。 例如:
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;
}
}
步驟9:建立productContext檔案的目錄
在與etc
目錄相同的層級,建立名為Plugin/Module
的目錄。 此目錄包含ProductContext.php
檔案。
步驟10:定義ProductContext類別
建立名為ProductContext.php
的檔案來定義ProductContext
類別。 例如:
<?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;
}
}
步驟11:註冊模組
在與etc
目錄相同的層級,建立登入模組的registration.php
檔案。 例如:
<?php>
declare(strict_types=1);
use \Magento\Framework\Component\ComponentRegistrar;
ComponentRegistrar::register(
ComponentRegistrar::MODULE,
'Magento_AepCustomAttributes',
__DIR__
);
步驟12:擴充您現有的XDM結構
為確保您的Commerce結構描述能夠在Experience Platform中擷取新的自訂訂單屬性,您需要擴充結構描述以包含這些自訂欄位。
若要瞭解如何擴充現有的XDM結構描述以包含這些自訂欄位,請參閱Experience Platform檔案中的在UI中建立及編輯結構描述一文。 租使用者ID欄位是動態產生的;但是,欄位結構應類似於Experience Platform檔案中提供的範例。
至commerce.order
,新增訂單層級的欄位:
至productListItems
,新增訂單專案層級的欄位:
步驟12:確認正在擷取資料
檢視Admin中的資料自訂索引標籤,以確認正在擷取自訂屬性資料並傳送給Experience Platform。
疑難排解
如果您在 Data Customization 標籤上看到訊息No custom order attributes found.
,請確認下列事項:
- 您已完成啟用Data Connector擴充功能的必要條件。
- 您已設定自訂訂單屬性。
- 至少已產生一個訂購事件。