README

要使用 CartBoss SDK，需要以下条件

• 免费注册CartBoss 账户。无需注册费用。
• 添加新的网站以获取 API 密钥。
• PHP >= 7.3
• 最新的 OpenSSL（或其他 SSL/TLS 工具包）

Composer 安装

安装 CartBoss SDK 最简单的方法是使用Composer进行要求。

$ composer require cartboss/cartboss-php:^2.0

{
    "require": {
        "cartboss/cartboss-php": "^2.0"
    }
}

开始之前

请花几分钟时间了解 CartBoss 的基本概念。

1. 事件

CartBoss 是一个基于事件的平台。我们的 SDK 包含构建、验证和将事件发送到 CartBoss（无论是“实时”还是从您的后端）所需的一切。

1.1. 添加到购物车事件

添加到购物车事件发生在访客离开您的网站而没有下订单时。由您决定何时对此情况适用，但最常见的方法是在访客更新结账字段（例如，姓名、电话、购物车商品等）时发送添加到购物车事件。

添加到购物车事件随后由 CartBoss 处理，并在我们的端为提供的电话号码创建一个遗弃购物车消息队列。如果没有收到后续的购买事件，CartBoss 将根据您的遗弃购物车自动化设置开始发送相应的消息。

发送相同订单的多个添加到购物车事件是完全正常的。

1.2. 购买事件

购买事件发生在访客下订单时。购买事件与添加到购物车事件非常相似，增加了一个 CartBoss 归因令牌（下文将解释）。

当 CartBoss 接收到特定订单的购买事件时，将销毁遗弃购物车序列中的所有剩余消息，并且永远不会发送。如果启用，将创建一个新的购买后序列。

因此，确保您从后端发送所有“已完成”订单的购买事件非常重要（例如，cronjob）。基本实现包括在您的订单表中添加一个新的布尔字段 send_cartboss_purchase，默认值设置为 false，一旦订单完成就更新为 true。

2. URL 拦截器

CartBoss 向您的联系人发送的大多数文本消息（短信）包含当点击时将他们带回到您的网站的 URL。

CartBoss 通过以“cb__”为前缀的一些特殊 URL 查询参数与您的网站“通信”。借助 CartBoss SDK，您可以通过注册的监听器轻松访问拦截的值。

2.1. 归因拦截器

CartBoss 的归因令牌（cb__att）是一个注入到指向您的网站的所有 URL 中的 64 字符哈希。它帮助 CartBoss 区分有机和基于 CartBoss 的购买。您的目标是拦截、存储并将归因令牌传递给购买事件，一旦订单成功完成。

注入归因令牌的示例 URL

https://www.your-site.com?cb__att=7zd1n87e8712z87nzdqs87z1278dnz1
https://store.your-site.com/path/?foo=bar&?cb__att=7zd1n87e8712z87nzdqs87z1278dnz1

2.2. 折扣拦截器

CartBoss 的折扣令牌（cb__discount）是一个加密并 URL 编码的包含三个值（类型|代码|值）的数组。它使您能够向访客发送动态优惠（例如，嗨 Mike，现在下单并享受整个订单 20% 的折扣。点击这里）。

注入折扣令牌的示例 URL

https://www.your-site.com?cb__discount=<encoded>
https://store.your-site.com/path/?foo=bar&?cb__discount=<encoded>

折扣拦截器验证、解码并返回有效的优惠券对象，如果通过短信消息提供折扣。

示例实现

我们的代码包括示例项目，可在以下链接找到：示例项目。如果您需要额外的帮助，请联系我们。

入门

1. 初始化CartBoss SDK

使用您的API密钥初始化CartBoss SDK库。建议尽早并在代码中的每个请求上初始化CartBoss SDK和注册URL拦截器。

$cartboss = new \CartBoss\Api\CartBoss("l33t87zd1n87e8712z87nzdqs87z1278dnz187wzne");

2. 注册归因拦截器

每次拦截到 归因令牌 并推送到您的 onAttributionIntercepted() 方法实现时，建议将其存储到会话/购物车/订单/数据库中，以供以后使用，因为您稍后将将其附加到购买事件。

$cartboss->onAttributionIntercepted(function(Attribution $attribution) {
    print $attribution->isValid(); // bool
    print $attribution->getToken(); // n87e8712z87nzdqs87z12712z87nzdq78dnz187w
    
    
});

3. 注册折扣拦截器

每次拦截到 折扣令牌 并推送到您的 onCouponIntercepted() 方法实现时，您应该将新的优惠券（如果尚未存在）插入到您的数据库中，并将其附加到访客的购物车/订单/会话。

$cartboss->onCouponIntercepted(function(Coupon $coupon) {
    print $attribution->isValid(); // bool
    print $attribution->getType(); // PERCENTAGE|FIXED_AMOUNT|FREE_SHIPPING|CUSTOM
    print $attribution->getValue(); // float
    print $attribution->getCode(); // str
    
    // helper methods
    print $attribution->isFreeShipping(); // bool
    print $attribution->isPercentage(); // bool
    print $attribution->isFixedAmount(); // bool
    print $attribution->isCustom(); // bool
});

4. 发送添加到购物车事件

添加到购物车事件通常在可用的新结账信息时发送。例如；当访客输入电话号码，设置名字或更新送货国家...

有两个非常重要的方面需要注意

• 通过 $order->setId("...") 提供的 order_id 是添加到购物车事件和购买事件之间的粘合剂。它告诉CartBoss之前“被遗弃”的订单现在“已购买”。
• 通过 $order->setCheckoutUrl("...") 提供的 checkout_url 指向您的脚本，该脚本应能够在新的浏览器（手机）中恢复之前被遗弃的会话/订单（桌面）。请记住，cookie在浏览器和/或webview（例如Facebook应用）之间是不共享的。

添加到购物车事件的简单示例。您可以在event_atc.php中找到完整示例。

// Create AddToCart event
$event = new AddToCartEvent();


// Create contact
$contact = new Contact();
$contact->setPhone("1234567");
$contact->setCountry("US");
$contact->setFirstName("Jake");
$contact->setAcceptsMarketing(true); // in case your site supports "consent checkout field"

// Add contact to event
$event->setContact($contact);

// Create order
$order = new Order();
$order->setId("1001"); // id that uniquely represents cart/order in your local database 
$order->setValue(19.99); // float 2 decimals 
$order->setCurrency('EUR'); // currency code

// Set publicly accessible url to the script that can restore visitor's order from provided order id  
// https://www.your-site.com/cartboss-restore-cart.php?order_id=1001
// https://www.your-site.com/cartboss-restore-cart.php?order_hash=9n12998as7as798d791dn988jdsa (if you don't want to expose db order_id)
$order->setCheckoutUrl("https://site.com/cartboss/cart_restore.php?order_id=1001"); 

// Add order to event
$event->setOrder($order);

// Send event to CartBoss
try {
    $cartboss->sendOrderEvent($event);

} catch (EventValidationException $e) {
    var_dump($e->getMessage());

} catch (ApiException $e) {
    var_dump($e->getMessage());
}

5. 恢复遗弃的购物车

每个遗弃的购物车短信都包括指向您网站的缩短URL（checkout_url）。URL是通过添加到购物车事件中的setCheckoutUrl()方法提供的。此处理程序必须公开可访问，并能够在新浏览器中恢复访客的旧会话。

此脚本的实现取决于您的业务逻辑，但在抽象实现中，它应执行以下操作

1. 解析URL参数以获取order_id
2. 从本地数据库中检索订单
3. 检查订单是否存在并且仍然处于“被遗弃”的状态
4. 将order_id存储到访客的会话中
5. 重定向到您的结账页面（附带utm_参数）
6. 否则，将访客重定向到您的首页

您可以在cart_restore.php中找到示例购物车恢复脚本。

6. 发送购买事件

当订单在您的商店上提交时，将发送购买事件。强烈建议从您的后端发送这些事件，例如1分钟cron作业。

购买事件的简单示例。您可以在event_purchase.php中找到完整示例。

// Create AddToCart event
$event = new PurchaseEvent();

// Attach attribution token, you have received through Attribution URL Interceptor when visitor visited your site 
// through SMS link.  
$event->setAttributionToken("...");

// Create contact
$contact = new Contact();
$contact->setPhone("1234567");
$contact->setCountry("US");
$contact->setFirstName("Jake");
$contact->setAcceptsMarketing(true); // in case your site supports "consent checkout field"

// Add contact to event
$event->setContact($contact);

// Create order
$order = new Order();
$order->setId("1001"); // id that uniquely represents cart/order in your local database 
$order->setValue(19.99); // float 2 decimals 
$order->setCurrency('EUR'); // currency code

// Add order to event
$event->setOrder($order);

// Send event to CartBoss
try {
    $cartboss->sendOrderEvent($event);

} catch (EventValidationException $e) {
    var_dump($e->getMessage());

} catch (ApiException $e) {
    var_dump($e->getMessage());
}

常见问题解答

问题：当向CartBoss发送添加到购物车事件时会发生什么？
答案：为提供的电话号码创建遗弃购物车短信队列 - 通常是一到三条短信。

问题：CartBoss何时停止发送遗弃购物车短信？
答案：当收到具有相同 $order->setId() 的购买事件时，或者队列中的所有短信都已发送。

问题：如果我在购买事件中没有提供归因令牌会发生什么？
答案：此类事件将不计入CartBoss统计，因为它被视为有机转化。

问题：我必须与添加到购物车事件一起发送什么checkout_url？
答案：发送给访客以在新移动浏览器中恢复会话/购物车的URL。

问题：我应该为我们在网站上进行的每次购买（有机的和CartBoss基础的）发送购买事件吗？
答案：是的

问题：如果发送事件失败我该怎么办？
答案：您可以简单地忽略添加到购物车错误，但应尽最大努力发送所有购买事件。

辅助工具

我们提供了一些辅助方法，以简化您的CartBoss SDK集成。

PHP

请参阅 CartBoss\Api\Utils 了解可用的辅助函数。

JS

有关更多信息，请参阅 CartBossJS。需要jQuery。