广点通SDK

简体中文 | English

内容列表

• 简介
• 安装
• 使用说明
  • 授权
  • 基础调用
  • 请求参数与响应类型
  • 自动翻页
  • 工厂
• 维护者
• 如何贡献
• 使用许可

简介

当前支持的API版本: v1.1

本仓库从 MrSuperLi/tencent-marketing-api-php-sdk 分支

相较于原仓库上的改动:

1. 集成授权
2. 客户端传入advertiser_id参数
3. 客户端按业务(资源)模块调用
4. 请求参数支持数组
5. 支持多种响应类型
6. 使用PSR-2

安装

composer install cloudycity/tencent-marketing-sdk

使用说明

• Auth: 获取、刷新令牌

• Client: 调用各资源的主客户端

• BaseClient: 发起动作的资源

• Factory: 用于获取自定义资源实例的工厂

授权

use CloudyCity\TencentMarketingSDK\Auth;
use CloudyCity\TencentMarketingSDK\Kernel\Exceptions\Exception;

$clientId = '';
$clientSecret = '';
$authCode = '';
$redirectUri = '';

$auth = new Auth($clientId, $clientSecret);

try {
    $res = $auth->getTokens($authCode, $redirectUri);
    $refreshToken = $res['data']['refresh_token'];

    $res = $auth->refreshTokens($refreshToken);
} catch (Exception $e) {
    //
}

基础调用

广点通接口格式统一为: 资源/动作

接口示例:

• funds/get 获取资金账户信息
• advertiser/update 更新广告主信息

资源对应Client对象中的属性，动作对应属性中的方法

调用示例:

$res = $client->funds->get();
$res = $client->advertiser->update($params);

请求参数与响应类型

use CloudyCity\TencentMarketingSDK\Client;
use CloudyCity\TencentMarketingSDK\Kernel\Http\Parameters\Params;
use CloudyCity\TencentMarketingSDK\Kernel\Exceptions\Exception;

$advertiserId = '';
$accessToken = '';

// 可以传入第三个参数来指定响应类型
// 支持的响应类型: array (default) / object / collection / raw (json string)
$client = new Client($advertiserId, $accessToken);

// 使用`Params`类来构建参数
$params = Params::make()->setDateRange('2020-01-01', '2020-01-07')
    ->set('level', 'REPORT_LEVEL_ADGROUP')
    ->groupBy('adgroup_id', 'date')
    ->orderBy('cost', 'desc');

$filter = $params->getFilter()
    ->eq('adgroup_id', 'xxx');

$params->setFilter($filter);

// 或使用数组构建参数
$params = [
    'date_range' => [
        'start_date' => '2020-01-01',
        'end_date' => '2020-01-07',
    ],
    'level' => 'REPORT_LEVEL_ADGROUP',
    'group_by' => [
        'adgroup_id',
        'date'
    ],
    'order_by' => [
        'sort_field' => 'cost',
        'sort_type' => 'DESCENDING'
    ],
    'filtering' => [
        [
            'adgroup_id',
            'EQUALS',
            'xxx'
        ]
    ]
];

try {
    $res = $client->daily_reports->get($params);
} catch (Exception $e) {
    //
}

自动翻页

BaseClient::getAllPages()通过Generator实现翻页逻辑.

use CloudyCity\TencentMarketingSDK\Client;
use CloudyCity\TencentMarketingSDK\Kernel\Exceptions\Exception;

$advertiserId = '';
$accessToken = '';
$client = new Client($advertiserId, $accessToken);

try {
    foreach ($client->campaigns->getAllPages() as $page) {
        foreach ($page as $record) {
            var_dump($record);
        }
    }
} catch (Exception $e) {
    //
}

工厂

如果API更新出现了新的资源名称，但是SDK版本未更新，Client对象将找不到对应的成员属性。 此时你可以通过工厂类获取一个BaseClient实例，建议同时提交新Issue让我给Client添加新的成员属性。

use CloudyCity\TencentMarketingSDK\Factory;

$advertiserId = '';
$accessToken = '';

$resourceClient = Factory::getClient('new_resource', $advertiserId, $accessToken);

维护者

• @CloudyCity

如何贡献

非常欢迎你的加入！提一个 Issue 或者提交一个 Pull Request。

标准 Readme 遵循 Contributor Covenant 行为规范。

使用许可

MIT © CloudyCity