README

简介

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

快速入门

商业 SDK 入门指南

先决条件

注册应用

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

要管理营销 API，请访问您的 应用仪表板 并将 营销 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": "5.0.5"
    }
}

然后通过 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）的bug，请在我们的开发者错误报告渠道报告问题。