README

入门

Zaius SDK 提供了 Zaius API 的编程接口，具体文档请参阅 https://developers.zaius.com/reference。

要开始使用，请在项目中包含该库

composer require zaius/zaius_sdk

您可以使用以下方式获取 Zaius 客户端的实例

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

API 密钥可以从您的 Zaius 账户在 https://app.zaius.com/app#/api_management 获取。点击“私有”选项卡并使用私有 API 密钥。

可用方法

客户管理

创建/更新客户

此方法接受一个包含客户对象或客户对象数组的单个数组

示例

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

获取客户

此方法接受一个包含以下可能键的筛选器数组

email
vuid
customer_id

请注意，您只需传递上述之一。此外，API 对每个字段仅支持精确匹配。

示例

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

事件

发布事件

发布事件。事件数组对象方法必须具有以下键

type - 事件的类型（例如，产品）
action - 事件的操作（例如，add_to_cart）
identifiers - 包含标识符的数组。有效的键是 vuid 和 email
data - 包含特定事件数据的数组。支持的完整值列表可在 https://developers.zaius.com/reference#upload-events 查找

您可以为批量上传传递事件数组。

示例

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

列表管理

创建列表

使用给定的名称创建列表。

示例

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

$zaiusClient->createList($list);

获取所有列表

返回所有列表。

示例

$lists = $zaiusClient->getLists();

更新列表

更新列表的名称。该方法期望以下参数

$listId - 要更改的列表的 ID（使用 getLists() 调用获取）
$newName - 列表的新名称

示例

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

订阅管理

获取订阅

根据筛选器获取订阅。接受的筛选器列表可在 https://developers.zaius.com/reference#get-subscriptions-1 查找。

示例

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

更新订阅

更新订阅。订阅数组可以有三个键

list_id（可选）- 要更新订阅的列表
email - 要更新订阅的电子邮件
subscribed - true/false - 是否订阅或取消订阅用户

该方法还支持传递订阅数组进行批量更新。

示例

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

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

更新渠道订阅

更新订阅。参数

optedIn - true/false
email - 电子邮件地址

示例

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

导出

导出所有对象

导出所有对象。参数

objects - 要导出的对象类型的数组，例如 array('orders','products')。留空以导出所有对象类型
format - csv, parquet 之一。默认为 csv
delimiter - comma, tab, pipe 之一。默认为逗号。

示例

$zaiusClient->exportAllObjects()

导出筛选对象

根据筛选器导出对象。

参数

filter - 如 https://developers.zaius.com/v3/reference#export-filtering 所述的筛选器数组
format - csv, parquet 之一。默认为 csv
delimiter - comma, tab, pipe 之一。默认为逗号。

示例

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

获取导出状态

获取导出状态。参数

exportId - 导出ID

示例

$zaiusClient->getExportStatus(1223233);

Schema API

获取所有可用对象

返回一个包含所有可用对象模式的数组。

示例

$zaiusClient->getObjects()

获取对象模式

返回指定对象的模式。

参数

objectType - 一个有效的对象类型。使用getObjects()方法获取所有对象类型

示例

 $zaiusClient->getObject('products')

创建新的对象类型

创建一个新的对象类型。参数

object (唯一) id
对象名称
别名
字段定义数组
关系定义数组

示例

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

获取对象的字段

获取对象的字段。参数

对象ID

示例

$zaiusClient->getObjectFields('products');

为对象创建新字段

为对象创建新字段。参数

对象ID
字段ID
字段类型
字段名称
字段描述

示例

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

获取所有对象的关系

获取对象的全部关系。参数

对象ID

示例

$zaiusClient->getRelations('products')

发布对象

发布产品

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

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

此方法也支持传递产品数组进行批量更新。

发布客户

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

此方法也支持传递客户数组进行批量更新。

发布订单

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

此方法也支持传递订单数组进行批量更新。

发布自定义对象

创建（或更新）对象。参数

对象ID
包含对象数据的数组。必须包含对象模式中要求的所有字段。

此方法支持传递对象数组进行批量更新。

示例

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

批量上传对象到S3

S3客户端可以从Zaius客户端获取

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

要获取所需的密钥，请检查https://developers.zaius.com/v3/reference#amazon-s3

事件

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

产品

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

客户

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

订单

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

支持的对象类型

所有Zaius方法都期望以特定格式传递数组。除了为每个对象列出的键之外，任何其他键/值对都接受，并将其作为自定义字段发送，如果它是通过Zaius仪表板/模式API定义的

要查看可用字段的完整列表，请登录到您的Zaius帐户后访问https://app.zaius.com/app#/custom_fields。

客户

示例

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

事件

示例

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

产品

示例

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

订单

示例

$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"
]];

通用API调用

虽然SDK涵盖了所有特定操作，但可以通过使用call()方法发起对API的一般调用。期望三个参数

$parameters - 参数数组。对于get调用，它们将作为url参数发送。对于post / put调用，它们将作为post字段发送
$method - 一个有效的http方法名称，例如post或get
$url - 完整端点url

此方法返回原始API响应。请注意，大多数情况下，这将是一个json编码的字符串。

如果响应代码不是20x或404，则方法抛出ZaiusException。404响应代码返回空主体，表示没有找到提供的查询的条目。

示例

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

批量处理

虽然Zaius API速度快，但可以通过使用批量处理完全解耦它。我们正在使用DJJob，https://github.com/seatgeek/djjob作为一个通用的队列机制。

设置

初始化mysql数据库

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

在调用队列推送之前，您需要确保mysql凭据已初始化

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

将事件推送到队列

所有发布方法都有一个队列bool参数，您可以将其设置为将事件推送到队列而不是立即处理

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

post调用的返回值将是推送对象的mysql插入ID。

您可以使用以下方式稍后处理队列

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

zaius / zaius-php-sdk

维护者

详细信息