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:

filter - an array with the filter as described at https://developers.zaius.com/v3/reference#export-filtering
format - one of csv, parquet. Defaults to csv
delimiter - one of comma,tab, pipe. Defaults to comma.

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

Example:

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

Events

Example:

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

Products

Example:

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

Orders

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();

zaius / zaius-php-sdk

Maintainers

Details

README

Getting Started

Available methods

Customer management

Create/update a customer

Get a customer

Events

Post an event

List management

Create a list

Get all lists

Update a list

Subscription management

Get subscriptions

Update subscription

Update channel opt-in

Exports

Export all objects

Export filtered objects

Get the export status

Schema API

Get all available objects

Get object schema

Create a new object type

Get an object's fields

Create a new field for an object

Get all object's relations

Posting objects

Post a product

Post a customer

Post an order

Posting custom objects

Bulk upload objects to S3

Events

Products

Customers

Orders

Supported object types

Customers

Events

Products

Orders

Generic API calls

Batch processing

Setup

Push events to the queue