README

简介

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

快速入门

Business SDK 入门指南

先决条件

注册应用

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

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

重要：出于安全考虑，建议您在应用的设置->高级页面中启用“服务器API调用应用密钥证明”。

获取访问令牌

当有人使用Facebook登录与应用连接并批准权限请求时，应用将获得一个访问令牌，该令牌提供了对Facebook API的临时、安全的访问权限。

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

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

有关更多信息，请参阅我们的 访问令牌指南。

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

安装

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

Composer

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