1C-BitrixのオンラインストアとMindboxの統合

ロイヤルティシステムを開発するために、オンラインストアはマーケティング自動化プラットフォームであるCustomer Data Platform（CDP）に目を向けています。同時に、統合を成功させるために、APIドキュメントに示されているよりも多くのデータを保存する必要がある場合があります。



1C-Bitrix上のストアをMindboxプラットフォームと統合するために必要なデータ、APIとSDKを使用してデータを取得する方法、および非同期データ送信と組み合わせたアプローチを使用する方法について説明します。







Customer Data Platformサービスの助けを借りて、小売業者は行動データを含む顧客の肖像を「認識」します。この情報はCDPに安全に保存され、小売業者がマーケティングキャンペーンや分析を行うのに役立ちます。



顧客がテレビまたはその他の製品をカートに追加すると、CDPはこのデータを保存します。それらに基づいて、小売業者はユーザーとのやり取りを拡大できます。たとえば、同様の製品の推奨事項や割引を提供できます。



私たちのクライアントの1つである電気店のチェーンは、Mindbox CDPプラットフォームに接続することを決定し、統合の支援を求めました。主要なユーザーシナリオ（承認、カートへの追加、支払いなど）の統合を実行しました。

バックグラウンド

オンラインストアは、APIまたはJavaScript SDKを使用する2つの主な方法でMindboxに接続できます（違いについては後で説明します）。



最善の方法を選択するために、Mindboxのドキュメントを参照し、十分な情報がない場合は、マネージャーに質問しました。私たちのコラボレーションは、Mindboxプラットフォームの急速な成長の時期と一致していることがわかりました。MindboxAPI呼び出しの1日の平均負荷は、2倍になりました（1分あたり最大12万リクエスト、ピーク時は最大25万リクエスト）。つまり、ブラックフライデーやその他の販売では、負荷がさらに増加し​​たため、CDPサービスが利用できなくなり、統合されたオンラインストアからデータを受信できなくなるリスクがありました。



Mindboxはこの問題に迅速に対応し、ITシステムのアーキテクチャとインフラストラクチャを改善して4倍の安全係数を達成し始めました。次に、購入データがMindboxにスムーズに送信されるようにする必要がありました。これには、最も信頼性の高い統合方法を選択する必要がありました。

マインドボックスの統合方法

上記のように、MindboxはAPIまたはJavaScriptSDKを使用して接続することをお勧めします。次に、それらの機能について検討します。

• JavaScript SDK

ライブラリは、サービスによって提供されるAPIの「ラッパー」です。その利点は、統合が容易であり、非同期データ転送が可能であることです。Webプラットフォームのみをサポートする必要がある場合に最適です。



制限事項：送信時にMindboxが使用できない場合、データが失われる可能性があります。オンラインストア側でjsエラーが発生した場合、プラットフォームスクリプトは読み込まれません。

• API統合

ストアとMindboxの統合は、APIを介して実行できます。この方法は、JavaScriptへの依存を減らし、非同期データ送信の設定にも適しています。



制限事項：一部のCookieデータ、つまりデバイス上のユーザーの一意の識別子（mindboxDeviceUUID）を受信しなかったという事実に直面しました。ユーザー情報を接着するには、ほとんどのMindbox操作で渡す必要があります。



ドキュメントでは、これらのCookieはすべての操作に必要なわけではありません。それでも、中断のないデータ送信を目指して、この問題についてMindboxのマネージャーと話し合いました。信頼性を最大化するには、常にCookieを送信することをお勧めします。ただし、Cookieを受信するにはJavaScriptSDKを使用する必要があります。

組み合わせた方法

上記の統合方法を検討しましたが、純粋な形ではプロジェクトに適していませんでした。小売業者のビジネス上の問題を解決し、ロイヤルティシステムを構築するには、Cookieの識別子を含む、ユーザーアクションに関するデータの完全なセットをMindboxに転送する必要がありました。同時に、JavaScriptへの依存と、Mindboxが一時的に利用できなくなった場合のデータ損失のリスクを減らすことを目指しました。



したがって、3番目の組み合わせた方法に目を向けました。キューモジュールを使用して、APIとJavaScriptSDKの両方を操作します。



Javascript SDKを使用して、サイト上のユーザーを識別します（mindboxDeviceUUID）。次に、サーバー側で、必要なすべてのデータを使用して要求を作成し、キューに入れます。 APIを介したキューからの要求は、Mindboxサービスに送信されます。答えが「いいえ」の場合、要求は再キューイングされます。したがって、データを送信するとき、Mindboxは必要な情報の完全なセットを受け取ります。



以下の例では、Senderクラスを使用すると、応答の初期処理を実行することにより、要求を収集して送信できます。このクラスは、コマンド自体（要求/応答のタイプ、deviceUUIDなど）およびモジュール設定（API、トークンなどを操作するためのパラメーター）からのデータを使用します。

<?php
declare(strict_types=1);

namespace Simbirsoft\MindBox;

use Bitrix\Main\Web\Uri;
use Bitrix\Main\Web\HttpClient;
use Simbirsoft\Base\Converters\ConverterFactory;
use Simbirsoft\MindBox\Contracts\SendableCommand;

class Sender
{
    /** @var Response   */
    protected $response;
    /** @var SendableCommand  */
    protected $command;

    /**
     * Sender constructor.
     *
     * @param SendableCommand $command
     */
    public function __construct(SendableCommand $command)
    {
        $this->command = $command;
    }

    /**
     *    .
     *
     * @return array
     */
    protected function getHeaders(): array
    {
        return [
            'Accept'        => Type\ContentType::REQUEST[$this->command->getRequestType()],
            'Content-Type'  => Type\ContentType::RESPONSE[$this->command->getResponseType()],
            'Authorization' => 'Mindbox secretKey="'. Options::get('secretKey') .'"',
            'User-Agent'    => $this->command->getHttpInfo('HTTP_USER_AGENT'),
            'X-Customer-IP' => $this->command->getHttpInfo('REMOTE_ADDR'),
        ];
    }

    /**
     *   .
     *
     * @return string
     */
    protected function getUrl(): string
    {
        $uriParts = [
            Options::get('apiUrl'),
            $this->command->getOperationType(),
        ];
        $uriParams = [
            'operation'  => $this->command->getOperation(),
            'endpointId' => Options::get('endpointId'),
        ];

        $deviceUUID = $this->command->getHttpInfo('deviceUUID');
        if (!empty($deviceUUID)) {
            $uriParams['deviceUUID'] = $deviceUUID;
        }

        return (new Uri(implode('/', $uriParts)))
            ->addParams($uriParams)
            ->getUri();
    }

    /**
     *  .
     *
     * @return bool
     */
    public function send(): bool
    {
        $httpClient = new HttpClient();

        $headers = $this->getHeaders();
        foreach ($headers as $name => $value) {
            $httpClient->setHeader($name, $value, false);
        }

        $encodedData = null;
        $request = $this->command->getRequestData();
        if (!empty($request)) {
            $converter = ConverterFactory::factory($this->command->getRequestType());
            $encodedData = $converter->encode($request);
        }

        $url = $this->getUrl();
        if ($httpClient->query($this->command->getMethod(), $url, $encodedData)) {
            $converter = ConverterFactory::factory($this->command->getResponseType());
            $response = $converter->decode($httpClient->getResult());
            $this->response = new Response($response);
            return true;
        }
        return false;
    }

    /**
     * @return Response
     */
    public function getResponse(): Response
    {
        return $this->response;
    }
}

Sendableトレイトには、Mindboxにリクエストを送信するためのすべての可能なコマンド設定が含まれています。これには、リクエスト/レスポンスのタイプ、リクエストメソッド、sync / asyncパラメータなどの事前定義されたものが含まれます。また、すべてのコマンドに共通のメソッドも含まれています。

<?php
declare(strict_types=1);

namespace Simbirsoft\MindBox\Traits;

use RuntimeException;
use Bitrix\Main\Context;
use Simbirsoft\MindBox\Type;
use Simbirsoft\MindBox\Sender;
use Simbirsoft\MindBox\Response;
use Bitrix\Main\Localization\Loc;
use Simbirsoft\MindBox\Contracts\SendableCommand;

Loc::loadMessages($_SERVER['DOCUMENT_ROOT'] .'/local/modules/simbirsoft.base/lib/Contracts/Command.php');

trait Sendable
{
    /** @var string   (GET/POST) */
    protected $method = Type\OperationMethod::POST;
    /** @var string   (sync/async) */
    protected $operationType = Type\OperationType::ASYNC;
    /** @var string   (json/xml) */
    protected $requestType = Type\ContentType::JSON;
    /** @var string   (json/xml) */
    protected $responseType = Type\ContentType::JSON;
    /** @var array   */
    protected $data = [];

    /**
     *  .
     * @return string
     */
    abstract public function getOperation(): string;

    /**
     *  .
     *
     * @return array
     */
    abstract public function getRequestData(): array;

    /**
     * HTTP  
     *
     * @return string
     */
    public function getMethod(): string
    {
        return $this->method;
    }

    /**
     *  
     *
     * @return string
     *
     * @noinspection PhpUnused
     */
    public function getOperationType(): string
    {
        return $this->operationType;
    }

    /**
     *  .
     *
     * @return string
     *
     * @noinspection PhpUnused
     */
    public function getRequestType(): string
    {
        return $this->requestType;
    }

    /**
     *  .
     *
     * @return string
     *
     * @noinspection PhpUnused
     */
    public function getResponseType(): string
    {
        return $this->responseType;
    }

    /**
     *   
     *
     * @return void
     */
    public function initHttpInfo(): void
    {
        $server = Context::getCurrent()->getServer();
        $request = Context::getCurrent()->getRequest();

        $this->data = [
            'X-Customer-IP' => $server->get('REMOTE_ADDR'),
            'User-Agent'    => $server->get('HTTP_USER_AGENT'),
            'deviceUUID'    => $request->getCookieRaw('mindboxDeviceUUID'),
        ];
    }

    /**
     *    
     *
     * @param string $key
     * @param string $default
     *
     * @return string
     *
     * @noinspection PhpUnused
     */
    public function getHttpInfo(string $key, string $default = ''): string
    {
        return $this->data[$key] ?? $default;
    }

    /**
     *  .
     *
     * @return void
     *
     * @throws RuntimeException
     */
    public function execute(): void
    {
        /** @var SendableCommand $thisCommand */
        $thisCommand = $this;
        $sender = new Sender($thisCommand);
        if ($sender->send()) {
            throw new RuntimeException(Loc::getMessage('BASE_COMMAND_NOT_EXECUTED'));
        }

        $response = $sender->getResponse();
        if (!$response->isSuccess()) {
            throw new RuntimeException(Loc::getMessage('BASE_COMMAND_NOT_EXECUTED'));
        }

        if (!$this->prepareResponse($response)) {
            throw new RuntimeException(Loc::getMessage('BASE_COMMAND_NOT_EXECUTED'));
        }
    }

    /**
     *   .
     *
     * @param Response $response
     *
     * @return bool
     */
    public function prepareResponse(Response $response): bool
    {
        // $body   = $response->getBody();
        // $status = $body['customer']['processingStatus'];
        /**
         *  :
         * AuthenticationSucceeded -   
         * AuthenticationFailed         -    
         * NotFound                          -    
         */
        return true;
    }
}

例として、ユーザー認証イベントについて考えてみます。承認イベントハンドラーで、AuthorizationCommandクラスのオブジェクトをキューに追加します。このクラスでは、コマンドの実行時にデータベース内のデータが変更される可能性があり、それらを保存する必要があるため、必要最小限の情報の準備が行われます。また、Mindboxのリクエストに対応するパラメータが設定されます。この場合、これは操作の名前です（Mindbox管理パネルにあります）。さらに、Sendable特性に従って、要求/応答のタイプ、要求メソッド、およびsync / asyncパラメーターを指定できます。

<?php
declare(strict_types=1);

namespace Simbirsoft\MindBox\Commands;

use Simbirsoft\Queue\Traits\Queueable;
use Simbirsoft\MindBox\Traits\Sendable;
use Simbirsoft\Queue\Contracts\QueueableCommand;
use Simbirsoft\MindBox\Contracts\SendableCommand;

final class AuthorizationCommand implements QueueableCommand, SendableCommand
{
    use Queueable, Sendable;

    /** @var array   */
    protected $user;

    /**
     * AuthorizationCommand constructor.
     *
     * @param array $user
     */
    public function __construct(array $user)
    {
        $keys = ['ID', 'EMAIL', 'PERSONAL_MOBILE'];
        $this->user = array_intersect_key($user, array_flip($keys));

        $this->initHttpInfo();
    }

    /**
     *  .
     *
     * @return string
     */
    public function getOperation(): string
    {
        return 'AuthorizationOnWebsite';
    }

    /**
     *  .
     *
     * @return array
     */
    public function getRequestData(): array
    {
        return [
            'customer' => [
                'email' => $this->user['EMAIL'],
            ],
        ];
    }
}

モジュール相互作用スキーム

私たちのプロジェクトでは、次の3つのモジュールを特定しました。

• ベース

プロジェクト全体で使用できる一般的なユーティリティクラスとインターフェイス（コマンドインターフェイスなど）を格納します。

• キューモジュール

Mindboxとの相互作用は、コマンドを介して実装されます。それらを順番に実行するには、キューモジュールを使用します。このモジュールは、着信コマンドを保存し、時が来たときにそれらを実行します。

• マインドボックス統合モジュール

このモジュールは、承認、登録、注文の作成、カートへの追加など、サイト上のイベントを「キャッチ」し、コマンドを生成してキューモジュールに送信します。







Mindboxモジュールは、Cookieからのものを含め、サイト上のイベントと関連情報を監視し、それらからコマンドを作成してキューに入れます。キューモジュールがキューからコマンドを取得して実行すると、データが送信されます。マインドボックスからの回答が否定的な場合、失敗したコマンドはキューの最後に移動され、肯定的な場合、成功したコマンドはキューから削除されます。



したがって、上記の組み合わせた方法を使用して、Mindboxへのスムーズなデータ転送を保証することができました。

まとめ

この記事では、オンラインストアがカスタマーデータプラットフォームに接続してロイヤルティシステムを開発する方法を検討しました。



この例では、2つの主要な接続方法がMindboxのドキュメントで説明されています。JavascriptSDK経由とAPI経由です。CDPサービスが一時的に利用できなくなった場合でも、データ送信の信頼性を向上させるために、APIとJavascript SDKを使用し、非同期データ送信を行う3番目の組み合わせ方法を選択して実装しました。



清聴ありがとうございました！この記事がお役に立てば幸いです。