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();

对于某些对象，广告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）中遇到错误，请在我们的开发者错误报告渠道报告问题。