README

提供构建将Nosto集成到您的电子商务平台的模块的工具。

要求

• Nosto PHP SDK需要至少PHP版本5.4.0，并且也兼容PHP >= 7.0.0

入门指南

创建新的Nosto账户

每个商店和每个商店中的每种语言都需要一个Nosto账户。

    .....
    try {
        /** @var NostoSignupInterface $meta */
        /** @var NostoSignup $account */
        $account = NostoSignup::create($meta);
        // save newly created account according to the platforms requirements
        .....
    } catch (NostoException $e) {
        // handle failure
        .....
    }
    .....

使用现有Nosto账户连接

当管理员用户想要将现有Nosto账户连接到商店时，应在商店的后端执行此操作。

首先重定向到Nosto OAuth2服务器。

    .....
    /** @var OAuthInterface $meta */
    $client = new NostoOAuthClient($meta);
  	header('Location: ' . $client->getAuthorizationUrl());

然后准备好一个公共端点来处理返回请求。

    if (isset($_GET['code'])) {
        try {
            /** @var OAuthInterface $meta */
            $account = NostoSignup::syncFromNosto($meta, $_GET['code']);
            // save the synced account according to the platforms requirements
        } catch (NostoException $e) {
            // handle failures
        }
        // redirect to the admin page where the user can see the account controls
        .....
    }
    } elseif (isset($_GET['error'])) {
        // handle errors; 3 parameter will be sent, 'error', 'error_reason' and 'error_description'
        // redirect to the admin page where the user can see an error message
        .....
    } else {
        // 404
        .....
    }

删除Nosto账户

当您要为商店删除Nosto账户时，应使用此功能。这将通知Nosto该账户不再使用。

    try {
        /** @var NostoSignup $account */
        $account->delete();
    } catch (NostoException $e) {
        // handle failure
    }

获取账户控制认证的Nosto URL

Nosto账户可以通过商店后端管理员用户可访问的控制面板创建和管理。账户控制面板将重定向到nosto.com。

    .....
    /**
     * @param ConnectionMetadataInterface $connection the connection meta data.
     * @param AccountInterface|null $account the configuration to return the url for.
     * @param UserInterface|null $user
     * @param array $params additional parameters to add to the connection url.
     */
    try
    {
        $url = Nosto::helper('connection')->getUrl($meta, $account, $user, $params);
    }
    catch (NostoException $e)
    {
        // handle failure
    }
    // render the link to the user with given url
    .....

使用Nosto API发送订单确认

将订单确认发送到Nosto是功能的关键部分。当商店中的订单完成时，应发送OrderConfirm确认。不建议在向用户显示“感谢”页面时执行此操作，因为支付网关的工作方式不同，并且您不能依赖于用户在支付后总是被重定向回商店。因此，建议在商店中将订单标记为已付款时发送订单确认。

OrderConfirm确认可以通过两种方式发送

• 匹配订单；我们知道放置订单的用户Nosto客户ID
• 未匹配订单：我们不知道放置订单的用户Nosto客户ID

Nosto客户ID由Nosto设置在名为“2c.cId”的cookie中，平台需要保持用户与Nosto客户ID之间的链接。建议将Nosto客户ID绑定到订单或购物车，而不是用户ID，因为平台可能支持匿名结账。

    .....
    try {
        /**
         * @var NostoOrderInterface $order
         * @var NostoSignupInterface $account
         * @var string $customerId
         */
        NostoOrderConfirmation::send($order, $account, $customerId);
    } catch (NostoException $e) {
        // handle error
    }
    .....

使用Nosto API发送产品重新爬取请求

注意：此功能已被以下方法（创建/更新/删除）取代。

当商店中的产品发生变化时（库存减少，价格更新等），建议向Nosto发送API请求以启动产品“重新爬取”事件。这是为了更新包括该产品在内的推荐，以便向网站上的用户显示最新信息。

注意：$product模型只需包括productId和url属性，其他都可以省略。

    .....
    try {
        /**
         * @var NostoProductInterface $product
         * @var NostoSignupInterface $account
         */
        NostoProductReCrawl::send($product, $account);
    } catch (NostoException $e) {
        // handle error
    }
    .....

也可以通过创建产品模型集合进行批量重新爬取

    .....
    try {
        /**
         * @var NostoExportProductCollection $collection
         * @var NostoProductInterface $product
         * @var NostoSignupInterface $account
         */
        $collection[] = $product;
        NostoProductReCrawl::sendBatch($collection, $account);
    } catch (NostoException $e) {
        // handle error
    }
    .....

使用Nosto API发送产品创建/更新/删除请求

当商店中的产品发生变化时（库存减少，价格更新等），建议向Nosto发送API请求以处理更新的产品信息。添加新产品以及删除现有产品也是如此。这是为了更新包括该产品在内的推荐，以便向网站上的用户显示最新信息。

创建新产品

    .....
    try {
        /**
         * @var NostoProductInterface $product
         * @var NostoSignupInterface $account
         */
        $op = new UpsertProduct($account);
        $op->addProduct($product);
        $op->create();
    } catch (NostoException $e) {
        // handle error
    }
    .....

注意：您可以多次调用addProduct以向请求添加更多产品。这样，您可以批量创建产品。

更新现有产品

    .....
    try {
        /**
         * @var NostoProductInterface $product
         * @var NostoSignupInterface $account
         */
        $op = new UpsertProduct($account);
        $op->addProduct($product);
        $op->update();
    } catch (NostoException $e) {
        // handle error
    }
    .....

注意：您可以多次调用addProduct方法来向请求中添加更多产品。这样，您可以批量更新产品。

删除现有产品

    .....
    try {
        /**
         * @var NostoProductInterface $product
         * @var NostoSignupInterface $account
         */
        $op = new UpsertProduct($account);
        $op->addProduct($product);
        $op->delete();
    } catch (NostoException $e) {
        // handle error
    }
    .....

注意：您可以多次调用addProduct方法来向请求中添加更多产品。这样，您可以批量删除产品。

导出Nosto可以请求的加密产品/订单信息

当为商店创建新的Nosto账户时，Nosto将尝试获取关于产品和订单的历史数据。这些信息用于启动推荐，并减少在商店中显示准确推荐所需的时间。

为此，Nosto需要2个公共端点，这些端点可以在通过API创建新账户后调用。这些端点应该提供使用AES加密的历史数据。SDK捆绑了使用纯PHP解决方案加密数据的能力（http://phpseclib.sourceforge.net/），建议但不强制要求在服务器上安装mcrypt。

此外，端点需要支持限制导出产品/订单的数量以及用于获取数据批次的偏移量。这些必须实现为GET参数"limit"和"offset"，这些参数将以整数形式发送，并预期应用于正在导出的数据集。

    .....
    /**
     * @var NostoProductInterface[] $products
     * @var NostoSignupInterface $account
     */
    $collection = new NostoExportProductCollection();
    foreach ($products as $product) {
        $collection[] = $product;
    }
    // The exported will encrypt the collection and output the result.
    $cipher_text = NostoExporter::export($account, $collection);
    echo $cipher_text;
    // It is important to stop the script execution after the export, in order to avoid any additional data being outputted.
    die();

    .....
    /**
     * @var NostoOrderInterface[] $orders
     * @var NostoSignupInterface $account
     */
    $collection = new NostoExportOrderCollection();
    foreach ($orders as $order) {
        $collection[] = $order;
    }
    // The exported will encrypt the collection and output the result.
    $cipher_text = NostoExporter::export($account, $collection);
    echo $cipher_text;
    // It is important to stop the script execution after the export, in order to avoid any additional data being outputted.
    die();

测试

SDK使用Codeception（http://codeception.com/）进行单元测试。

运行测试

首先cd到根目录。

然后通过composer安装Codeception。

    php composer.phar install

然后运行测试。

    vendor/bin/codecept run

测试新添加的操作

SDK单元测试使用apiary作为存根服务器。apiary从master分支拉取api-blueprint.md，并基于它构建假API端点。在将其合并到master之前测试新添加的操作的方法是使用运行在Node上的Drakov API Blueprint Mock Server（https://github.com/Aconex/drakov）。

首先cd到根目录。

然后通过composer安装Codeception。

    php composer.phar install

之后，您可以通过npm安装drakov服务器。

    npm install -g drakov

更新tests/.env文件中的端点。

    NOSTO_API_BASE_URL=localhost:3000
    NOSTO_OAUTH_BASE_URL=localhost:3000/oauth
    NOSTO_WEB_HOOK_BASE_URL=https://:3000

然后使用API蓝图启动drakov模拟服务器。

    drakov -f tests/api-blueprint.md

然后在另一个窗口中运行测试。

    vendor/bin/codecept run

您可以为调试目的向drakov服务器传递debugMode标志。

    drakov -f tests/api-blueprint.md --debugMode

运行phpcs

首先cd到根目录。

然后运行phpcs。

    phpcs --standard=ruleset.xml -v .