README

介绍

Facebook 商业 SDK 是一个一站式商店，帮助我们的合作伙伴更好地服务他们的业务。合作伙伴正在使用多个 Facebook API 来满足客户的需求。采用所有这些 API 并在各个平台间保持它们更新可能耗时且最终具有阻碍性。因此，Facebook 开发了商业 SDK，将许多 API 打包成一个 SDK，以简化实施和维护。商业 SDK 是营销 API SDK 的升级版，包括营销 API 以及来自不同平台（如页面、商务管理、Instagram 等）的许多 Facebook API。

快速开始

商业 SDK 入门指南

先决条件

注册应用程序

要开始使用 SDK，您必须在 developers.facebook.com 上注册一个应用程序。

要管理营销 API，请访问您的 应用程序仪表板 并将 营销 API 产品添加到您的应用程序中。

重要：出于安全考虑，建议您在应用程序的设置->高级页面中开启“要求应用程序密钥”。

获取访问令牌

当某人通过 Facebook 登录与应用程序连接并批准权限请求时，应用程序会获取一个访问令牌，该令牌提供了临时、安全的 Facebook API 访问权限。

访问令牌是一个不透明的字符串，用于标识用户、应用程序或页面。

例如，要访问营销 API，您需要为您的应用程序生成用户访问令牌并请求 ads_management 权限；要访问页面 API，您需要为您的应用程序生成页面访问令牌并请求 manage_page 权限。

请参阅我们的 访问令牌指南 了解更多信息。

目前，我们可以使用 Graph Explorer 来获取访问令牌。

安装

Facebook 商业 SDK 需要 PHP 5.6 或更高版本。

Composer

Facebook 商业 SDK 使用 composer 来管理依赖项。访问 composer 文档 了解如何安装 composer。

将以下内容添加到您的 composer.json 文件中

{
    "require": {
        "facebook/php-business-sdk": "12.0.*"
    }
}

然后通过 composer 安装它

php composer.phar install --no-dev

此 SDK 及其依赖项将安装在 ./vendor 下。

替代方案

此存储库遵循 psr-4 自动加载标准。任何 psr-4 兼容的自动加载器都可以使用。

使用

API 主类

FacebookAds\Api 对象是商业 SDK 的基础，它封装了一个 FacebookAds\Session 并用于对 Graph API 执行请求。

要实例化一个 Api 对象，您需要一个有效的访问令牌

use FacebookAds\Api;

// Initialize a new Session and instantiate an Api object
Api::init($app_id, $app_secret, $access_token);

// The Api object is now available through singleton
$api = Api::instance();

一旦实例化，Api对象将允许您开始向Graph API发送请求。

字段名称

由于Graph API中现有对象字段数量众多，为了便于您维护代码，提供了枚举类。这些文件存储在FacebookAds/Object/Fields目录下。您可以使用与在php中相同的方式访问对象属性。

use FacebookAds\Object\AdAccount;

$account = new AdAccount();
$account->name = 'My account name';
echo $account->name;

或使用枚举

use FacebookAds\Object\AdAccount;
use FacebookAds\Object\Fields\AdAccountFields;

$account = new AdAccount();
$account->{AdAccountFields::NAME} = 'My account name';
echo $account->{AdAccountFields::NAME};

对象类

Facebook Ads实体定义为存储在FacebookAds/Object目录下的类。

读取对象

use FacebookAds\Object\AdAccount;

$account = (new AdAccount($account_id))->getSelf();

对于某些对象，Ads API默认不返回所有可用的字段。对象的读取方法的第一参数是要请求的字段名称数组。

use FacebookAds\Object\AdAccount;
use FacebookAds\Object\Fields\AdAccountFields;

$fields = array(
  AdAccountFields::ID,
  AdAccountFields::NAME,
);

$account = (new AdAccount($account_id))->getSelf($fields);

请求大量字段可能会导致响应时间明显增加，您应该始终只请求真正需要的字段。

创建对象

use FacebookAds\Object\AdSet;
use FacebookAds\Object\AdAccount;
use FacebookAds\Object\Fields\AdSetFields;

$account_id = 'act_123123';
$campaign_id = '123456';

$account = new AdAccount($account_id);
$adset = $account->createAdSet(
    array(),
    array(
      AdSetFields::NAME => 'My Test AdSet',
      AdSetFields::CAMPAIGN_ID => campaign_id,
      AdSetFields::DAILY_BUDGET => 150,
      AdSetFields::START_TIME => (new \DateTime("+1 week"))->format(\DateTime::ISO8601),
      AdSetFields::END_TIME => (new \DateTime("+2 week"))->format(\DateTime::ISO8601),
      AdSetFields::BILLING_EVENT => 'IMPRESSIONS',
      AdSetFields::TARGETING => array('geo_locations' => array('countries' => array('US'))),
      AdSetFields::BID_AMOUNT => '1000',
    )
);

echo $adset->id;

更新对象

use FacebookAds\Object\AdSet;
use FacebookAds\Object\Fields\AdSetFields;

$ad_set_id = '123456';

$set = new AdSet($ad_set_id);
$fields = array(
);
$params = array(
  AdSetFields::NAME => 'My new AdSet name',
);
$set->updateSelf($fields, $params);

删除对象

use FacebookAds\Object\AdSet;

$ad_set_id = '123456';

$set = new AdSet($ad_set_id);
$set->deleteSelf();

游标

自Facebook Graph API 2.0发布以来，分页通过游标处理。在这里，游标定义为\FacebookAds\Cursor。游标通常由连接方法返回。

use FacebookAds\Object\AdAccount;
use FacebookAds\Object\Fields\CampaignFields;

$account = new AdAccount('<ACT_ID>');
$cursor = $account->getCampaigns(['id','name']);

// Loop over objects
foreach ($cursor as $campaign) {
  echo $campaign->{CampaignFields::NAME}.PHP_EOL;
}

// Access objects by index
if ($cursor->count() > 0) {
  echo "The first campaign in the cursor is: ".$cursor[0]->{CampaignFields::NAME}.PHP_EOL;
}

// Fetch the next page
$cursor->fetchAfter();
// New Objects will be appended to the cursor

隐式获取

当需要获取与父对象相关联的所有对象时（从HTTP请求的数量来看可能是粗心大意），隐式获取可以帮助减少所需的代码量。如果游标启用了隐式获取，则在迭代（foreach、Cursor::next()、Cursor::prev()）时，达到页面末尾，SDK将自动获取并附加新页面，直到游标末尾。隐式获取会使您失去对将发送的HTTP请求数量的控制，因此默认情况下禁用。可以为特定游标启用隐式获取。

$cursor->setUseImplicitFetch(true);

或全局

use FacebookAds\Cursor;

Cursor::setDefaultUseImplicitFetch(true);

反向迭代

游标是双向的，可以以反向顺序迭代。

use FacebookAds\Object\AbstractCrudObject;

/** @var \FacebookAds\Cursor $cursor */
$cursor->setUseImplicitFetch(true);

$cursor->end();
while ($cursor->valid()) {
  echo $cursor->current()->{AbstractCrudObject::FIELD_ID}.PHP_EOL;
  $cursor->prev();
}

测试

'test'文件夹包含测试用例。这些测试用例在单元测试和集成测试中进行逻辑划分。集成测试需要一个活动的Facebook Ad账户、一个Facebook应用程序和有效的访问令牌。

注意：我们目前无法在公共CI系统上安全且可靠地运行集成测试。我们的Travis和Scrutinizer集成（包括此文件顶部的徽章）仅包括单元测试。

安装依赖项

从根目录运行

php composer.phar install --dev

仅执行单元测试

./vendor/bin/phpunit -c test/phpunit-travis.xml

要单独运行测试（确保不是指向集成测试文件）

./vendor/bin/phpunit -c test/phpunit-travis.xml path/to/class/file

执行所有测试（单元+集成）

设置您的集成配置

1 - 复制配置文件模板。

cp test/config.php.dist test/config.php

2 - 使用您的信息编辑test/config.php。

执行

./vendor/bin/phpunit -c test/

要单独运行测试

./vendor/bin/phpunit -c test/ path/to/class/file

调试

如果此SDK未按预期工作，可能是SDK问题或API问题。

这可以通过构造原始cURL请求并查看响应是否如预期来识别。

例如

require __DIR__ . '/vendor/autoload.php';
use FacebookAds\Api;
use FacebookAds\Object\AdAccount;

Api::init($app_id, $app_secret, $access_token);
$api = Api::instance();

use FacebookAds\Logger\CurlLogger;
$api->setLogger(new CurlLogger());
$account = new AdAccount($account_id);
$account->read(array('id'));

运行此代码时，此cURL请求将打印到控制台

curl -G \
  -d 'fields=id' \
  -d 'access_token=<access_token>' \
  https://graph.facebook.com/v3.1/<act_accountid>

SDK Codegen

我们的SDK是从SDK Codegen自动生成的。如果您想了解更多关于我们SDK代码是如何生成的信息，请检查此存储库。

问题

为了更有效地处理错误，我们已决定关闭在GitHub上的问题报告，并将其转移到我们专门的错误报告渠道。如果您在使用Business SDK（PHP）时遇到错误，请在我们开发者错误报告渠道中报告问题。