PHP SDK

1 使用场景

DataNexus 的数据上报 API 可使用腾讯广告 Marketing API SDK进行调用。该 SDK 提供了 Token获取、请求封装、响应解释等功能，以本地化方式轻松完成API的调用和结果的获取，旨在帮助开发者快速搭建数据上报系统。

2 使用条件

1. 使用 SDK 需要首先注册成为腾讯广告开发者，请参考开发者快速入门文档
2. 使用 SDK 需要先拥有 API 的访问权限，所有SDK的使用与应用拥有的权限组相关联
3. PHP SDK 需要依赖 PHP 5.5 及以上

3 使用步骤

3.1 如何安装

1. 修改composer.json文件，添加如下内容

{
  "require": {
    "tencent-ad/marketing-api-php-sdk" : "*"
  }
}

1. 执行如下命令安装

composer install --no-dev

3.2 如何使用

SDK 同时支持数组参数和语义化调用，推荐使用数组参数，方便后续升级扩展。本说明文档都使用数组参数调用的形式。/docs目录下的文档使用了语义化调用的方式。 SDK数组参数调用的方法名与API接口一一对应，如user_actions/add接口就对应$tads->userActions()->add()方法

获取Access Token

信息

DataNeuxs - 数据源接入功能支持一键生成 Access Token（具有数据上报权限组，有效期为永久）。如使用一键生成的 Access Token，可跳过本步骤。

注：本示例适用于授权时通过Authorization Code获取Access Token和Refresh Token，如需更新Access Token请参考 ./examples/refresh_token.php 示例

<?php
require_once __DIR__ . '/vendor/autoload.php'; // vendor 目录中的 autoload 文件
use TencentAds\TencentAds;

$tads = TencentAds::init([]);
$token = $tads->oauth()
              ->token([ // oauth/token接口即对应oauth()->token()方法
                  'client_id'          => '{your client id}',
                  'client_secret'      => '{your client secret}',
                  'grant_type'         => 'authorization_code',
                  'authorization_code' => '{your authorization code}',
                  'redirect_uri'       => '{your redirect uri}',
              ]);

echo "<pre>" . PHP_EOL;
print_r($token);
echo "</pre>" . PHP_EOL;

$tads->setAccessToken($token->getAccessToken());

设置调用环境、Access Token

<?php
require_once __DIR__ . '/vendor/autoload.php';
use TencentAds\TencentAds;

$tads = TencentAds::init([
    'access_token' => '{access-token}',
])->useSandbox(); // 默认访问沙箱环境，如访问正式环境，请调用$tads->useProduction()

调用API接口

<?php
require_once __DIR__ . '/../../../vendor/autoload.php'; // change path as needed
use TencentAds\TencentAds;
use TencentAds\Exception\TencentAdsResponseException;
use TencentAds\Exception\TencentAdsSDKException;

/*****
 * 本文件提供了一个创建用户行为数据(User action)的简单示例
 */
class AddUserActions
{
    public static $tads;
    public static $ACCESS_TOKEN       = 'YOUR ACCESS TOKEN';
    public static $ACCOUNT_ID         = 'YOUR ACCOUNT ID';
    public static $USER_ACTION_SET_ID = 'YOUR USER ACTION SET ID'; // 数据源ID
    public static $USER_HASH_IMEI     = 'YOUR USER IMEI'; // 用户IMEI
    public static $USER_ACTION_TYPE   = 'CUSTOM'; // 自定义行为
    public static $USER_CUSTOM_ACTION = 'YOUR CUSTOM ACTION TYPE'; // 自定义行为类型

    public function init()
    {
        $tads = TencentAds::init([
            'access_token' => static::$ACCESS_TOKEN,
            'is_debug'     => true,
        ]);
        $tads->useSandbox(); // 默认访问沙箱环境，如访问正式环境，请切换为$tads->useProduction()
        static::$tads = $tads;

        return $tads;
    }

    public function main()
    {
        try {
            /* @var TencentAds $tads */
            $tads = static::$tads;

            $actions = [
                [
                    'action_time'   => time(),
                    'user_id'       => [
                        'hash_imei' => static::$USER_HASH_IMEI,
                    ],
                    'action_type'   => static::$USER_ACTION_TYPE,
                    'custom_action' => static::$USER_CUSTOM_ACTION,
                ],
            ];
            $response = $tads->userActions()
                             ->add([
                                 'account_id'         => static::$ACCOUNT_ID,
                                 'user_action_set_id' => static::$USER_ACTION_SET_ID,
                                 'actions'            => $actions,

                             ]);

            return true;
        } catch (TencentAdsResponseException $e) {
            // When Api returns an error
            echo 'Tencent ads returned an error: ' . $e->getMessage() . PHP_EOL;
            throw $e;
        } catch (TencentAdsSDKException $e) {
            // When validation fails or other local issues
            echo 'Tencent ads SDK returned an error: ' . $e->getMessage() . PHP_EOL;
            throw $e;
        } catch (Exception $e) {
            echo 'Other exception: ' . $e->getMessage() . PHP_EOL;
            throw $e;
        }
    }
}

if (basename($_SERVER['PHP_SELF']) == basename(__FILE__)) {
    try {
        $example = new AddUserActions();
        $example->init();
        $example->main();
    } catch (\Exception $e) {
        exit(-1);
    }
}

调试和查看API接口日志

<?php
require_once __DIR__ . '/vendor/autoload.php'; 

use TencentAds\TencentAds;

$tads = TencentAds::init([
    'access_token' => '{access-token}',
    'is_debug'     => true,
    'debug_file'   => '{your log path}', // 不指定，输出到 php://output
]);

关闭SDK上报

目前SDK上报信息为您的服务器版本和PHP版本信息，为了帮助您更好地定位使用上的问题，建议开启上报，如需关闭请参考如下配置。

<?php
require_once __DIR__ . '/vendor/autoload.php'; 

use TencentAds\TencentAds;

$tads = TencentAds::init([
    'access_token' => '{access-token}',
    'is_monitor'   => false,
]);

设置返回数组

<?php
require_once __DIR__ . '/vendor/autoload.php'; 

use TencentAds\TencentAds;
use TencentAds\Kernel\SerializerHandler;

$tads = TencentAds::init([
    'access_token' => '{access-token}',
    'is_monitor'   => false,
]);

$tads->setSerializerType(SerializerHandler::SERIALIZER_TYPE_ARRAY);

该内容是否有帮助？