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 8.0 或更高版本。

Composer

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

在您的项目根目录中执行以下命令

composer require facebook/php-business-sdk

此 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代码生成

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

问题

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