zaius/zaius-php-sdk

The Zaius SDK for PHP. Validated for use in zaius-magento-2, users in custom environments are encouraged to test and validate thoroughly (and note any issues via the GitHub issue tracker).

1.0.1 2019-12-11 17:44 UTC

README

Getting Started

The Zaius SDK provides a programmatic interface for the Zaius API as documented at https://developers.zaius.com/reference .

To get started, include the library in your project:

composer require zaius/zaius_sdk

You can get an instance of the Zaius client using:

$zaiusClient = new \ZaiusSDK\ZaiusClient($apiKey);

The API key can be obtained from your Zaius account at https://app.zaius.com/app#/api_management . Click on the "Private" tab and use the private API key.

Available methods

Customer management

Create/update a customer

The method takes in a single array with the customer object or an array of customer objects

Example:

$profile = array();
$profile['email'] = 'test3@example.com';
$ret = $zaiusClient->postCustomer($profile);

Get a customer

This method takes in a filter array with the following possible keys:

  • email
  • vuid
  • customer_id

Note that you need to pass only one of the above. Also, the API supports only exact matches for each field.

Example:

$filter = ['email'=>'clay@example.com'];
$profile = $zaiusClient->getCustomer($filter);

Events

Post an event

Posts an event. The event array object method must have the following keys:

  • type - the type of the event (i.e. product)
  • action - the event's action (i.e. add_to_cart)
  • identifiers - an array with the identifiers. Valid keys are vuid and email
  • data - an array with the event-specific data. The full list of the supported values is available at https://developers.zaius.com/reference#upload-events

You can pass an array of events for bulk upload.

Example:

$event = array();
$event['type'] = 'test';
$event['action'] = 'test';
$event['identifiers'] = ['vuid'=>'test'];
$event['data'] = ['a'=>'b'];
$ret = $zaiusClient->postEvent($event);

List management

Create a list

Creates a list with the given name.

Example:

$list = array();
$list['name'] = uniqid();

$zaiusClient->createList($list);

Get all lists

Returns all lists.

Example:

$lists = $zaiusClient->getLists();

Update a list

Updates a list's name. The method expects the following parameters:

  • $listId - the ID of the list to change (get it with a getLists() call)
  • $newName - the new name for the list

Example:

$zaiusClient->changeListName('madison_island_newsletter','Renamed list');

Subscription management

Get subscriptions

Gets subscriptions based on a filter. The lists of accepted filters is available at https://developers.zaius.com/reference#get-subscriptions-1 .

Example:

$filters = ['email'=>'janesmith@example.com'];
$subscriptions = $zaiusClient->getSubscriptions($filters);

Update subscription

Updates a subscription. The subscription array can have three keys:

  • list_id (optional) - the list for which to update the subscription
  • email - the email to update the subscription for
  • subscribed - true/false - whether to subscribe or unsubscribe the user

The method also supports passing an array of subscriptions for bulk updates.

Example:

$subscription = array();
$subscription['list_id'] = 'zaius_all';
$subscription['email'] = 'janesmith@example.com';
$subscription['subscribed'] = true;

$ret = $zaiusClient->updateSubscription($subscription);

Update channel opt-in

Updates a subscription. Parameters:

  • optedIn - true/false
  • email - email address

Example:

$zaiusClient->updateChannelOptIn(false,'janesmith@example.com');

Exports

Export all objects

Exports all objects. Parameters:

  • objects - array with objects type to export, i.e. array('orders','products'). Leave empty to export all object types
  • format - one of csv, parquet. Defaults to csv
  • delimiter - one of comma,tab, pipe. Defaults to comma.

Example:

$zaiusClient->exportAllObjects()

Export filtered objects

Export objects given a filter.

Parameters:

Example:

$zaiusClient->exportObjectsWithFilters(array('object'=>'events'));

Get the export status

Gets the status of an export. Parameters:

  • exportId - the export id

Example:

$zaiusClient->getExportStatus(1223233);

Schema API

Get all available objects

Returns an array with all available objects schemas.

Example:

$zaiusClient->getObjects()

Get object schema

Returns the schema for the specified object.

Parameters:

  • objectType - a valid object type. Get all object types with the getObjects() method

Example:

 $zaiusClient->getObject('products')

Create a new object type

Creates a new object type. Parameters:

  • object (unique) id
  • object name
  • alias
  • field definition array
  • relation definition array

Example:

$fields =  [
    [
        'name' => 'object_id',
        "display_name"=> "New Object Identifier",
        "type"=> "string",
        "primary"=> true
    ],
    [
        "name"=> "another_field",
        "display_name"=> "Another Fields",
        "type"=> "string"
    ],
    [
        "name"=> "child_id",
        "display_name"=> "Child Identifier",
        "type"=> "number"
    ]
];

$relations = [
];

$zaiusClient->createObjectSchema('test_objects', 'Test Object', 'test_object', $fields, $relations);
        

Get an object's fields

Gets the fields for an object. Parameters:

  • object id

Example:

$zaiusClient->getObjectFields('products');

Create a new field for an object

Creates a new field for an object. Parameters:

  • object id
  • field id
  • field type
  • field name
  • field description

Example:

$zaiusClient->createObjectField('products','test_field','string','Test field','Test description');

Get all object's relations

Gets all relations for an object. Parameters:

  • object id

Example:

$zaiusClient->getRelations('products')

Posting objects

Post a product

$product = array();
$product['name'] = "Test product";
$product['sku'] = 'test-sku';
$product['product_id'] = 32;

$ret = $zaiusClient->postProduct($product);

This method also supports passing an array of products for bulk updates.

Post a customer

$profile = array();
$profile['email'] = 'test3@example.com';
$ret = $zaiusClient->postCustomer($profile);

This method also supports passing an array of customers for bulk updates.

Post an order

$order = array();
$order['name'] = "Test customer";
$order['order_id'] = '11111';
$order['total'] = 32;
$order['items'] = [[
    "product_id"=>"765",
    "sku"=>"zm64",
    "quantity"=>"1",
    "subtotal"=>"59.95"
]];

$ret = $zaiusClient->postOrder($order);

This method also supports passing an array of orders for bulk updates.

Posting custom objects

Creates (or updates) an object. Parameters:

  • object id
  • array with the object data. Must include all required fields per the object's schema.

This method supports passing an array of objects for bulk updates.

Example:

$zaiusClient->postObject('products',['product_id'=>33,'name'=>'test product']);

Bulk upload objects to S3

The S3 client can be obtained from the Zaius Client:

$zaiusClient = new \ZaiusSDK\ZaiusClient($apiKey);
$s3Client = $zaiusClient->getS3Client(ZAIUS_TRACKER_ID,ZAIUS_S3_KEY_ID,ZAIUS_S3_SECRET);

To get the needed keys, check https://developers.zaius.com/v3/reference#amazon-s3

Events

$event1 = array();
$event1['type'] = 'product';
$event1['action'] = 'addtocart';
$event1['identifiers'] = ['customer_id'=>99];
$event1['data'] = ['hostname'=>'127.0.0.1','page'=>'Bar'];


$event2 = array();
$event2['type'] = 'product';
$event2['action'] = 'addtocart';
$event2['identifiers'] = ['customer_id'=>99];
$event2['data'] = ['hostname'=>'127.0.0.1','page'=>'Foo'];

$events = [$event1,$event2];

$s3Client->uploadEvents($events);

Products

$product1 = array();
$product1['product_id'] = 1;
$product1['sku'] = '1234';
$product1['name'] = "Planet of the Apes";
$product1['category'] = 'Books';


$product2 = array();
$product2['product_id'] = 2;
$product2['sku'] = '4321';
$product2['name'] = "Escape from Planet of the Apes";
$product2['category']  = 'Movies';


$products = [
    $product1,$product2
];

$s3Client->uploadProducts($products);

Customers

$customer1 = array();
$customer1['customer_id'] = 1100;
$customer1['email'] = "floyd22@example.com";
$customer1['first_name'] = "Floyd";
$customer1['last_name'] = 'Dogg';
$customer1['foo'] = 'bar';

$customer2 = array();
$customer2['customer_id'] = 1200;
$customer2['email'] = "johnny22@example.com";
$customer2['first_name'] = "Johnny";
$customer2['last_name'] = 'Zaius';
$customer2['foo']='bar';

$customers = [
    $customer1,$customer2
];

$s3Client->uploadCustomers($customers);

Orders

$orderData = [];
$order1 = array();
$order1['order_id'] = '1009';
$order1['items']=[[
    "product_id"=>"765",
    "sku"=>"zm64",
    "quantity"=>"1",
    "subtotal"=>"59.95"
]];
$order1['subtotal'] = 6.99;
$order1['tax'] = 0;
$order1['shipping'] = 25.75;
$order1['total'] = 32.74;
$order1['email'] = 'floyd@zaius.com';
$order1['first_name'] = 'Floyd';
$order1['last_name'] = 'Dogg';
$order1['phone'] = '123456780';

$orderData['order'] = $order1;
$orderData['identifiers'] = ['ts'=>1460392935,'ip'=>'192.168.1.1','email'=>'floyd@zaius.com','action'=>'purchase'];

$orders = [$orderData];



$s3Client->uploadOrders($orders);

Supported object types

All Zaius methods expect arrays in a specific format. Besides the keys listed for each object, any other key/value pair is accepted and will be sent as a custom field, if it was defined via the Zaius dashboard/schema API

To see the full list of available fields, access https://app.zaius.com/app#/custom_fields after logging in into your Zaius account.

Customers

Key Type Other details
email string
gender string
name string
first_name string
last_name string
phone string
timezone string The timezone of the user in the following format: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
street1 string
street2 string
city string
state string
zip string
country string
image_url string
customer_id string

Example:

$customer = array();
$customer['email'] = 'test3@example.com';

Events

Key Type Other details
type string
action string
identifiers.email string
identifiers.vuid string
data.ts integer Timestamp of the event in unix time (epoch time). Automatically set to now if not present.
data.product_id string
data.category string
data.channel string
data.ua string User agent
data.ip string
data.title string
data.hostname string
data.page string
data.source string
data.medium string
data.campaign string
data.content string
data.keywords string
data.language string
data.character_set string
data.days_since_last_visit integer
data.landing bool
data.referrer string
data.search_term string
data.filter_field string
data.filter_value string
data.sort_direction string
data.sort_field string

Example:

$event = array();
$event['type'] = 'test';
$event['action'] = 'test';
$event['identifiers'] = ['vuid'=>'test'];
$event['data'] = ['a'=>'b'];

Products

Key Type Other details
brand string
category_id integer
description string
image_url string
is_in_stock bool
name string
parent_product_id integer
price number
product_id string
qty integer
sku string
special_price number
special_price_from_date timestamp
special_price_to_date timestamp
upc string

Example:

$product = array();
$product['name'] = "Test product";
$product['sku'] = 'test-sku';
$product['product_id'] = 32;

Orders

Key Type Other details
bill_address string
coupon_code string
first_name string
last_name string
name string
discount number
email string
order_id string
phone string
ship_address string
shipping number
status text
subtotal number
tax number
total number
user_id string
items.product_id string
items.sku string
items.quantity integer
items.subtotal number

Example:

$order = array();
$order['name'] = "Test customer";
$order['order_id'] = '11111';
$order['total'] = 32;
$order['items'] = [[
    "product_id"=>"765",
    "sku"=>"zm64",
    "quantity"=>"1",
    "subtotal"=>"59.95"
]];

Generic API calls

While the SDK covers all specific operations, it is possible to initiate a general call to the API by using the call() method. Three parameters are expected:

  • $parameters - an array of parameters. For get calls, they will be sent as url parameters. For post / put calls, they will be sent as post fields
  • $method - a valid http method name, i.e. post or get
  • $url - the full endpoint url

The method returns the raw API response. Note that most of the time, this will be a json encoded string.

The method throws a ZaiusException in case the response code is any other than 20x or 404. A 404 response code returns a null body and represents the fact that no entry was found for the provided query.

Example:

$zaiusClient = $this->getZaiusClient(ZAIUS_PRIVATE_API_KEY);
$filter = ['email'=>'clay@example.com'];
$profile = json_decode($zaiusClient->call($filter,'get',ZaiusClient::API_URL_V3.'/profiles'),true);

Batch processing

While the Zaius API is fast, it is possible to completely decouple it by using batch processing. We are making use of DJJob, https://github.com/seatgeek/djjob as a general queueing mechanism.

Setup

Initialize the mysql database:

mysql my_database < vendor/seatgeek/djjob/jobs.sql

Before making a call to push to the queue, you need to ensure that the mysql credentials were initialized:

$zaiusClient->setQueueDatabaseCredentials([
    'driver' => 'mysql',
    'host' => '127.0.0.1',
    'dbname' => 'my_database',
    'user' => 'my_user',
    'password' => 'my_password',
]);

Push events to the queue

All posting methods have a queue bool parameter that you can set to push to the queue instead of processing instantly:

$profile = array();
$profile['email'] = 'test3@example.com';
$ret = $zaiusClient->postCustomer($profile,true);


$product = array();
$product['name'] = "Test product";
$product['sku'] = 'test-sku';
$product['product_id'] = 32;
$ret = $zaiusClient->postProduct($product,true);

The returned value from the post calls will be the mysql insert id of the pushed object.

You can later process the queue with:

$worker = new \ZaiusSDK\Zaius\Worker();
$worker->processAll();