README

目录

• 需求
• 使用
  • 包含库
  • REST 客户端
  • 客户令牌
  • 验证 Webhook 消息

需求

• PHP 5.5
• PHP cURL 扩展

使用

包含库

使用 Phar 包

require 'phar://antavo-loyalty-sdk.phar';

// Now you can use the classes inside the archive.

REST 客户端

Antavo API REST 客户端是一个用于执行 API 请求的小型客户端。

它使用两个其他库

• Antavo\SignedToken 来处理 Web 令牌。
• Escher 是一个用于签名 HTTP 请求并验证它们的库。它通用化 AWS 使用的签名方法。
• Pakard\RestClient 是一个小型、通用的 REST 客户端。

创建实例

$client = new Antavo\Loyalty\Sdk\RestClient('REGION', 'API KEY', 'API SECRET');

在哪里

• REGION 是凭证作用域的一部分（用于签名请求），它由账户确定；
• API KEY 识别账户本身；
• API SECRET 用于签名请求。

API 端点基本 URL 使用 REGION 计算（尽管可以通过 setBaseUrl() 方法更改）。

发送请求

底层客户端有一个具有以下签名的 send() 方法

public function send(string $method, string $url, mixed $data = NULL): mixed;

它使得执行任何类型的 REST 请求成为可能

$response = $client->send('GET', '/customer/' . $customer->id);

$response 将包含解析后的 JSON 响应。

$response = $client->send(
    'POST',
    '/events',
    [
        'customer' => $customer->id,
        'action' => 'profile',
        'data' => [
            'email' => $customer->email,
        ]
    ]
);

简写

发送事件

// Assuming $customer is some kind of model object instance.
$client->sendEvent(
    $customer->id,
    'profile',
    [
        'email' => $customer->email,
        'custom_field' => get_custom_value(),
    ]
);

错误处理

注意，API 可能返回 2xx 以外的 HTTP 状态码，在这种情况下，客户端会抛出异常。

因此，强烈建议将所有请求包装在 try-catch 中

try {
    $result = $client->send('GET', '/customer');
} catch (\Pakard\RestClient\StatusCodeException $e) {
    // You can still retrieve the original (error) response:
    $result = $client->getResponse()->getBody();
}

可能发生其他类型的异常，所有都是 Pakard\RestClient\Exception 的后代

• Pakard\RestClient\ResponseParserException 在有误的响应体上；
• Pakard\RestClient\TransportException 在 PHP cURL 扩展产生的任何错误上。

客户令牌

Antavo\Loyalty\Sdk\CustomerToken 用于创建和验证 Web 令牌以在嵌入式忠诚度中心中验证客户。

创建实例

// Initializing a new token with the secret and with expiration time.
$token = new Antavo\Loyalty\Sdk\CustomerToken('API SECRET', $expires_in);

• 用于将散列附加到令牌的 API SECRET，以便以后可以验证。
• $expires_in 是一个整数值：令牌被认为有效的时间数。0 表示没有过期，小于 30 天（以秒为单位）的值被认为是生存时间，更大的值被视为 Unix 时间戳。

在实例化时，令牌会根据环境设置默认的 cookie 域，可以通过 setCookieDomain() 覆盖。

创建新令牌

可以通过设置客户 ID 来检索它，然后简单地将令牌对象转换为字符串

echo (string) (new Antavo\Loyalty\Sdk\CustomerToken('API SECRET', $expires_in))
    ->setCustomer($customer->id);

客户令牌在 cookie 中

设置客户令牌 cookie

$token = (new Antavo\Loyalty\Sdk\CustomerToken('API SECRET', $expires_in))
    ->setCustomer($customer->id);

if (!$token->setCookie()) {
    // Couldn't set the cookie...
}

然后取消设置

$token->unsetCookie();

检索 cookie 值

$token = new Antavo\Loyalty\Sdk\CustomerToken('API SECRET', $expires_in);

try {
    if (isset($_COOKIE[$token->getCookieName()]) {
        $token->setToken($_COOKIE[$token->getCookieName()]);
    }
} catch (Antavo\SignedToken\Exceptions\Exception $e) {
    // The token is either expired or invalid...
}

验证 Webhook 消息

在某些情况下，您需要处理由 Antavo 发送的 webhook 消息。您也可以使用 REST 客户端来验证此类请求

// Creating a REST client with valid region and credentials
// (though credentials won't be used for authentication -- see below).
$client = new Antavo\Loyalty\Sdk\RestClient('REGION', 'API KEY', 'API SECRET');

// Obtaining a configured Escher client from the REST client.
$escher = $client->createEscher();

// Authenticating current request using credential key-value pairs.
$escher->authenticate(
    [
        'API KEY' => 'API SECRET'
    ]
);

有关更多详细信息，请参阅EscherPHP 文档页面。