README

Table of Contents

• Requirements
• Usage
  • Including the Library
  • The REST Client
  • Customer Token
  • Validating Webhook Messages

Requirements

• PHP 5.5
• PHP cURL extension

Usage

Including the Library

Using the Phar package

require 'phar://antavo-loyalty-sdk.phar'; // Now you can use the classes inside the archive.

The REST client

The Antavo API REST client is a small client to perform requests to the API.

It uses two other libraries:

• Antavo\SignedToken to handle web tokens.
• Escher is a library to sign HTTP requests, also to validate them. It generalizes the signature method used by AWS.
• Pakard\RestClient is a small, generic REST client.

Creating an instance

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

Where:

• REGION is part of the credential scope (used to sign the request), it is determined by the account;
• API KEY identifies the account itself;
• API SECRET used to sign the request.

API endpoint base URL is calculated using REGION (though it can be changed via the setBaseUrl() method).

Sending a request

The underlying client has a send() method with the following signature:

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

It makes possible to perform any kind of REST request:

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

$response will hold the parsed JSON response.

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

Shorthands

Sending an event

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

Error Handling

Note that the API may return a HTTP status code other than 2xx, in which case the client throws an exception.

Because of that it is strongly recommended to wrap all requests in 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(); }

There may occur other kind of exceptions, all descendants of Pakard\RestClient\Exception:

• Pakard\RestClient\ResponseParserException on malformed response body;
• Pakard\RestClient\TransportException on any error produced by the PHP cURL extension.

Customer Token

Antavo\Loyalty\Sdk\CustomerToken is used to create & validate web tokens to authenticate the customer in the embedded loyalty hub.

Creating an instance

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

• API SECRET used to attach a hash to the token, so later it can be validated.
• $expires_in is an integer value: the number of seconds the token considered valid. 0 means no expiration, values smaller than 30 days (in seconds) considered as time-to-live, anything bigger is taken as a Unix timestamp.

Upon instantiation the token sets itself a default cookie domain from the environment, that can be override via setCookieDomain().

Creating a new token

It can be retrieved by setting a customer ID, then simply casting the token object to string:

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

Customer token in cookie

Setting a customer token cookie:

$token = (new Antavo\Loyalty\Sdk\CustomerToken('API SECRET', $expires_in)) ->setCustomer($customer->id); if (!$token->setCookie()) { // Couldn't set the cookie... }

Then unsetting it:

$token->unsetCookie();

Retrieving cookie value

$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... }

Validating Webhook Messages

There are cases when you need to handle webhook messages sent by Antavo. You can also use the REST client to authenticate such requests:

// 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' ] );

For further details see the EscherPHP documentation page.