README

这是一个用于 SmartFocus API 的 PHP 库。

这个库提供了对 SmartFocus（以前称为 EmailVision）[Campaign Commander 的 API] 的访问 [http://developer.smartfocus.com/io-docs](http://developer.smartfocus.com/io-docs)。它设计时考虑了灵活性，具有完全解耦的组件，因此开发人员可以轻松地将自己的组件注入和使用。

需求

PHP 5.x+
curl
libxml

安装

composer require estina/smartfocus

使用

与 API 的交互可以简化为以下基本步骤

打开连接并从 XML 响应中提取安全令牌
使用令牌和其他必需参数调用 API 方法
关闭连接

请参阅以下 [示例] (#api-examples)。

HTTP 传输到实际 REST 接口是在 Api\Http\CurlClient 类中实现的。只要实现了一个非常简单的 Api\Http\ClientInterface，就可以使用不同的类对象。

支持的 API 和方法

[成员 REST] (#member-rest) - 单个订阅管理
[批量成员 REST] (#batch-member-rest) - 批量订阅管理
[通知 REST] (#notification-rest) - 通知（邮件发送）服务

成员 REST

openConnection($server, $login, $password, $key)
closeConnection($token)
[insertMemberByEmailAddress($token, $email)] (#memberinsertmemberbyemailaddresstoken-email)
insertMember($token, $xml)
updateMember($token, $xml)
[insertOrUpdateMember($token, $xml)] (#memberinsertorupdatemembertoken-xml)
updateMemberByEmailAddress($token, $email, $field, $value)
getMemberJobStatus($token, $jobId)
getMemberByEmail($token, $email)
getMemberByCellphone($token, $cellphone)
getMemberById($token, $memberId)
getMembersByPage($token, $page)
getMembersByCriteria($token, $xml)
getMemberTableColumnNames($token)
unsubscribeMemberByEmail($token, $email)
unsubscribeMemberByCellphone($token, $cellphone)
unsubscribeMemberById($token, $memberId)
unsubscribeMemberByValue($token, $xml)
resubscribeMemberByEmail($token, $email)
resubscribeMemberByCellphone($token, $cellphone)
resubscribeMemberById($token, $memberId)

批量成员 REST

openConnection($server, $login, $password, $key)
closeConnection($token)
buildInsertXml($filepath, $dateformat = 'yyyy-MM-dd', $dedup = true)
insert($token, $xml)
buildUpdateXml($filepath, $dateformat = 'yyyy-MM-dd')
update($token, $xml)
getLastUpload($token)
getUploadStatus($token, $uploadId)
getUploads($token, $page, $pageSize = 1000, $sort = null, $status = null, $source = null)
getLogFile($token, $uploadId)
getBadFile($token, $uploadId)

通知 REST

[send($email, $encrypt, $notificationId, $random, $dyn, $senddate, $uidkey, $stype)] (#notificationsendemail-encrypt-notificationid-random-dyn-senddate-uidkey-stype)
buildTransactionalRequestObject($recipientEmail, $encryptId, $randomId, $dyn, $content, $enableTracking, $additionalParams)
post(SimpleXMLElement $xmlRequestObject)

API 示例

Member::insertMemberByEmailAddress($token, $email)

// cURL client for communication with API
use Estina\SmartFocus\Api\Http\CurlClient;
// Member REST API class
use Estina\SmartFocus\Api\Rest\Member;
// helper for XML parsing (optional)
use Estina\SmartFocus\Api\Util\RestResponseParser;

// initialize object, injecting the cURL client
$api = new Member(new CurlClient());

// open the connection, XML is returned, containing token or error description
$xmlResponse = $api->openConnection(
    'server hostname',
    'your login name',
    'your password',
    'your API key'
);

if ($xmlResponse) {
    // extract token from XML
    $parser = new RestResponseParser();
    $token = $parser->getResult($xmlResponse);

    if ($token) {

        // call the API method and fetch the response
        $insertResponse = $api->insertMemberByEmailAddress(
            $token,
            'email@example.com'
        );

        // close the connection
        $api->closeConnection($token);
    }
}

Member::insertOrUpdateMember($token, $xml)

// cURL client for communication with API
use Estina\SmartFocus\Api\Http\CurlClient;
// Member REST API class
use Estina\SmartFocus\Api\Rest\Member;
// helper for XML parsing (optional)
use Estina\SmartFocus\Api\Util\RestResponseParser;

// initialize object, injecting the cURL client
$api = new Member(new CurlClient());

// open the connection, XML is returned, containing token or error description
$xmlResponse = $api->openConnection(
    'server hostname',
    'your login name',
    'your password',
    'your API key'
);

if ($xmlResponse) {
    // extract token from XML
    $parser = new RestResponseParser();
    $token = $parser->getResult($xmlResponse);

    if ($token) {

        /*
         * Let's build request's XML body with data
         *
         * <memberUID>:
         *      Multiple sets of criteria can be combined to identify the member, e.g.
         *      EMAIL:johnsmith@smartfocus.com|LASTNAME:Smith
         *
         * <dynContent>:
         *      envelope containing the list of fields to be updated and their values
         *
         * <entry>:
         *      The entry envelope containing the field to update and its value.
         *
         * <key>:
         *      The field that will be updated.
         *
         * <value>:
         *      The value with which to update the field.
         */
        $xml =
            '<?xml version="1.0" encoding="utf-8"?>
             <synchroMember>
                <memberUID>EMAIL:%s</memberUID>
                <dynContent>
                    <entry>
                        <key>FIRSTNAME</key>
                        <value>%s</value>
                    </entry>
                    <entry>
                        <key>LASTNAME</key>
                        <value>%s</value>
                    </entry>
                </dynContent>
            </synchroMember>';

        // inject values into XML
        $xml = sprintf($xml, 'email@example.com', 'John', 'Smith');

        // call the API method and fetch the response
        $insertResponse = $api->insertOrUpdateMember($token, $xml);
        // close the connection
        $api->closeConnection($token);
    }
}

Notification::send($email, $encrypt, $notificationId, $random, $dyn, $senddate, $uidkey, $stype)

// cURL client for communication with API
use Estina\SmartFocus\Api\Http\CurlClient;
// Member REST API class
use Estina\SmartFocus\Api\Rest\Notification;

// initialize object, injecting the cURL client
$api = new Notification(new CurlClient());

$response = $api->send(
    'email@example.com',             // Recipient
    'abcdefg',                       // Encrypt value provided in the interface
    '132456',                        // ID of the Template
    '123456789',                     // Random value provided for the template
    'firstname:John|lastname:Smith', // Dynamic parameters as a string
    'YYYY-MM-DD HH:MM:SS',            // optional, The time you wish to send
    'email',                          // optional, the key you wish to update, normally email
    'NOTHING'                        // optional, The type of synchronization
);

Notification::post(SimpleXMLElement $xmlRequestObject)

// cURL client for communication with API
use Estina\SmartFocus\Api\Http\CurlClient;
// Member REST API class
use Estina\SmartFocus\Api\Rest\Notification;

// initialize object, injecting the cURL client
$api = new Notification(new CurlClient());

$recipientEmail = 'email@example.com';
$encryptId = 'abcdefg';
$randomId = '132456';

$additionalParams = [
    'senddate'      => 'YYYY-MM-DDTHH:MM:SS', // 'T' between date & time
    'uidkey'        => 'email',
    'synchrotype'   => 'NOTHING'
];

// Optional: Dynamic parameters as an array
$dyn = [
    'firstname' => 'John',
    'lastname' => 'Smith'
];

$content = [
    'click <a href="http://somewhere.com">here</a> please',
    'good stuff is available <a href="http://goodstuff.com">here</a>'
];

// Tracking enabled for the links passed in the content blocks.
$enableTracking = true;

// Build request object.
$xmlRequestObject = $api->buildTransactionalRequestObject(
    $recipientEmail,
    $encryptId,
    $randomId,
    $dyn,
    $content,
    $enableTracking,
    $additionalParams
);

// Make the request.
$response = $api->post($xmlRequestObject);

故障排除

如果您收到以下状态代码的响应

UPDATE_MEMBER_FAILED
ISTUPD_MEMBER_FAILED

请检查以下内容

XML 输入体格式正确
标签内没有空格、换行符或其他无效符号，它应该看起来像

<memberUID>EMAIL:email@example.com</memberUID>

estina / smartfocus

维护者

详情