Introdução ao SDK de Negócios da Meta

Este documento explica como instalar o SDK de Negócios da Meta e testar a instalação. Os SDKs estão disponíveis para Java, JavaScript, PHP, Python e Ruby. Se você já tem a API de Marketing instalada, saiba como atualizar para o SDK de Negócios da Meta.

Antes de começar

Você precisará do seguinte:

• Uma conta de desenvolvedor da Meta
• Um app da Meta registrado com as configurações básicas definidas
• Sua chave secreta do app
• Uma conta de anúncios
• Um token de acesso à Página

Java

Para apps Java, é possível usar qualquer ambiente de desenvolvimento, desde que ele ofereça suporte para compilações do Maven.

Instalar o SDK

Para o seu projeto do Maven, adicione o seguinte código XML à seção dependency do seu arquivo pom.xml:

<!-- https://mvnrepository.com/artifact/com.facebook.business.sdk/facebook-java-business-sdk -->
<dependency>
    <groupId>com.facebook.business.sdk</groupId>
    <artifactId>facebook-java-business-sdk</artifactId> 
    <version>[8.0.3,)</version>
</dependency>

Criar uma classe Java

Em src/main/java, crie uma classe Java chamada TestFBJavaSDK e adicione o seguinte código. Substitua {access-token}, {appsecret} e {adaccount-id} pelos seus valores.

import com.facebook.ads.sdk.APIContext;
import com.facebook.ads.sdk.APINodeList;
import com.facebook.ads.sdk.AdAccount;
import com.facebook.ads.sdk.Campaign;

public class TestFBJavaSDK
{
    public static final APIContext context = new APIContext(
            "{access-token}",
            "{appsecret}"
    );
    public static void main(String[] args)
    {
        AdAccount account = new AdAccount("act_{{adaccount-id}}", context);
        try {
            APINodeList<Campaign> campaigns = account.getCampaigns().requestAllFields().execute();
            for(Campaign campaign : campaigns) {
                System.out.println(campaign.getFieldName());
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }}

Testar a instalação

Compile e execute o app. O resultado aparecerá na janela de registro do console. Caso você receba um alerta de expiração, solicite um novo token de acesso à Página e tente novamente.

JavaScript (Node.js)

Para apps JavaScript, o SDK é distribuído como um pacote Node.js.

Abra a janela do terminal de comando e crie uma nova pasta do projeto. Crie, configure e instale o projeto com o seguinte comando:

npm init

É possível atualizar as definições de configuração mais tarde, editando o próprio arquivo package.json.

Instalar o SDK

Instale o pacote do SDK com o seguinte comando:

npm install --save facebook-nodejs-business-sdk

Modificar o arquivo do projeto

Abra o arquivo index.js e adicione o seguinte código. Substitua {access-token} e {adaccount-id} pelos seus valores.

const bizSdk = require('facebook-nodejs-business-sdk');

const accessToken = '{access-token}';
const accountId = 'act_{{adaccount-id}}';

const FacebookAdsApi = bizSdk.FacebookAdsApi.init(accessToken);
const AdAccount = bizSdk.AdAccount;
const Campaign = bizSdk.Campaign;

const account = new AdAccount(accountId);
var campaigns;
    
account.read([AdAccount.Fields.name])
  .then((account) =>{
    return account.getCampaigns([Campaign.Fields.name], { limit: 10 }) // fields array and params
  })
  .then((result) =>{
    campaigns = result
    campaigns.forEach((campaign) =>console.log(campaign.name))  
  }).catch(console.error);

Testar a instalação

Teste a instalação com o seguinte comando:

 node index.js

O resultado aparecerá na janela do terminal. Caso você receba um alerta de expiração, solicite um novo token de acesso à Página e tente novamente.

PHP

Para apps PHP, use o Composer para instalar o SDK.

Instalar o SDK

Em uma nova pasta do projeto, crie composer.json com o seguinte conteúdo. Substitua {project-name}, {Your Name} e {your@email.com} pelos seus valores.

{
    "name": "name/{project-name}",
    "type": "project",
    "require": {
        "facebook/php-business-sdk": "^8.0.3"
    },
    "authors": [
        {
            "name": "{Your Name}",
            "email": "{your@email.com}"
        }
    ]
}

Instale o SDK executando o seguinte comando na janela do terminal:

composer install

Criar um arquivo de projeto

Crie um arquivo src/test.php com o seguinte conteúdo. Substitua {app-id}, {access-token}, {appsecret} e {adaccount-id} pelos seus valores.

<?php
require_once __DIR__ . '/../vendor/autoload.php';
use FacebookAds\Api;
use FacebookAds\Logger\CurlLogger;
use FacebookAds\Object\AdAccount;
use FacebookAds\Object\Campaign;
use FacebookAds\Object\Fields\CampaignFields;

$app_id = "{app-id}";
$app_secret = "{appsecret}";
$access_token = "{access-token}";
$account_id = "act_{{adaccount-id}}";

Api::init($app_id, $app_secret, $access_token);

$account = new AdAccount($account_id);
$cursor = $account->getCampaigns();

// Loop over objects
foreach ($cursor as $campaign) {
  echo $campaign->{CampaignFields::NAME}.PHP_EOL;
}

Testar a instalação

Teste a instalação com o seguinte comando:

php src/test.php

O resultado aparecerá na janela do terminal. Caso você receba um alerta de expiração, solicite um novo token de acesso à Página e tente novamente.

Python

Para apps Python, o SDK é distribuído como um módulo pypi, então certifique-se de ter o pip instalado. Dependendo do seu sistema, você talvez precise configurar virtualenv, pyenv ou conda.

Instalar o SDK

Instale o SDK com o seguinte comando.

pip install facebook_business

Criar um arquivo de projeto

Crie o arquivo test.py com o seguinte conteúdo. Substitua {app-id}, {access-token}, {appsecret} e {adaccount-id} pelos seus valores.

from facebook_business.api import FacebookAdsApi
from facebook_business.adobjects.adaccount import AdAccount

my_app_id = '{app-id}'
my_app_secret = '{appsecret}'
my_access_token = '{access-token}'
FacebookAdsApi.init(my_app_id, my_app_secret, my_access_token)
my_account = AdAccount('act_{{adaccount-id}}')
campaigns = my_account.get_campaigns()
print(campaigns)

Testar a instalação

Teste a instalação com o seguinte comando:

python test.py

O resultado aparecerá na janela do terminal. Caso você receba um alerta de expiração, solicite um novo token de acesso à Página e tente novamente.

Ruby

Para Ruby, o SDK é distribuído como um pacote RubyGem.

Instalar o SDK

Na janela do terminal, execute o seguinte comando a partir da pasta do projeto para instalar o SDK de Negócios da Meta para Ruby. Dependendo do seu ambiente, talvez seja necessário configurar rbenv ou rvm ou usar sudo antes do comando.

gem install facebookbusiness

Criar um arquivo de projeto

Crie um arquivo test.rb com o seguinte conteúdo. Substitua {access-token}, {appsecret} e {adaccount-id} pelos seus valores.

require 'facebookbusiness'
FacebookAds.configure do |config|
  config.access_token = '{access-token}'
  config.app_secret = '{appsecret}'
end

ad_account = FacebookAds::AdAccount.get('act_{{adaccount-id}}', 'name')
ad_account.campaigns(fields: 'name').each do |campaign|
  puts campaign.name
end

Testar a instalação

Teste a instalação com o seguinte comando:

ruby test.rb

O resultado aparecerá na janela do terminal. Caso você receba um alerta de expiração, solicite um novo token de acesso à Página e tente novamente.

Para usuários existentes da API de Marketing

Para atualizar para o SDK de Negócios da Meta a partir da API de Marketing, siga estas etapas.

Java

No arquivo pom.xml:

• Atualize groupId de com.facebook.ads.sdk para com.facebook.business.sdk.
• Atualize artifactId de facebook-java-ads-sdk para facebook-java-business-sdk.
• Atualize version para v8.0.3.

Nodejs

No arquivo package.json:

• Atualize facebook-nodejs-ads-sdk para facebook-nodejs-business-sdk:v8.0.2.
• Atualize todas as referências do nome do pacote facebook-nodejs-ads-sdk, como require('facebook-nodejs-ads-sdk'), para facebook-nodejs-business-sdk.
• Execute npm install.

PHP

No arquivo composer.json:

• Atualize facebook-ads-sdk para facebook-business-sdk com a versão 8.0.3.

Python

• Execute pip install facebook_business.
• Atualize todas as referências do namespace facebookads para facebook_business.
• Se você tiver um arquivo .egg-info, atualize-o a partir de facebookads-*.egg-info para o novo arquivo egg-info instalado, como facebook_business-*.egg-info.

Ruby

• Execute gem install facebookbusiness.
• Atualize todas as referências de require('facebook_ads') para require('facebookbusiness').

Saiba mais

Veja o código fonte do SDK de Negócios da Meta no GitHub.