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

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