Facebook Business SDK for NodeJS

Introduction

The Facebook Business SDK is a one-stop shop to help our partners better serve their businesses. Partners are using multiple Facebook API's to serve the needs of their clients. Adopting all these API's and keeping them up to date across the various platforms can be time consuming and ultimately prohibitive. For this reason Facebook has developed the Business SDK bundling many of its APIs into one SDK to ease implementation and upkeep. The Business SDK is an upgraded version of the Marketing API SDK that includes the Marketing API as well as many Facebook APIs from different platforms such as Pages, Business Manager, Instagram, etc.

This SDK can be used for both server side as well as client side. It comes with ECMAScript 5 bundled minified distribution with source maps of AMD, CommonJS modules, IIFE, as UMD and as Browser Globals.

Quick Start

Business SDK Getting Started Guide

Pre-requisites

Dependencies

Gulp and Bower should be installed globally. Install dependencies:

``bash npm install bower install

Checkout gulpfile.js for all available tasks.
Register An App
To get started with the SDK, you must have an app
registered on <a href="https://developers.facebook.com/" target="_blank">developers.facebook.com</a>.
To manage the Marketing API, please visit your
<a href="https://developers.facebook.com/apps/<YOUR APP ID>/dashboard"> App Dashboard </a>
and add the <b>Marketing API</b> product to your app.
IMPORTANT: For security, it is recommended that you turn on 'App Secret
Proof for Server API calls' in your app's Settings->Advanced page.
Obtain An Access Token
When someone connects with an app using Facebook Login and approves the request
for permissions, the app obtains an access token that provides temporary, secure
access to Facebook APIs.
An access token is an opaque string that identifies a User, app, or Page.
For example, to access the Marketing API, you need to generate a User access token
for your app and ask for the ads_management permission; to access Pages API,
you need to generate a Page access token for your app and ask for the manage_page permission.

Refer to our
<a href="https://developers.facebook.com/docs/facebook-login/access-tokens" target="_blank">
Access Token Guide</a> to learn more.
For now, we can use the
<a href="https://developers.facebook.com/tools/explorer" target="_blank">Graph Explorer</a>
to get an access token.
Installation
NPM
npm install --save facebook-nodejs-business-sdk

Bower
bower install --save facebook-nodejs-business-sdk

Usage
Access Token
When someone connects with an app using Facebook Login and approves the request for permissions, the app obtains an access token that provides temporary, secure access to Facebook APIs.
An access token is an opaque string that identifies a User, app, or Page.
For example, to access the Marketing API, you need to generate a User access token for your app and ask for the ads_management permission; to access Pages API, you need to generate a Page access token for your app and ask for the manage_page permission.
Refer to our <a href="https://developers.facebook.com/docs/facebook-login/access-tokens" target="_blank">Access Token Guide</a> to learn more.

For now, we can use the <a href="https://developers.facebook.com/tools/explorer" target="_blank">Graph Explorer</a> to get an access token.

javaScript
const adsSdk = require('facebook-nodejs-business-sdk');
const accessToken = '';
const api = adsSdk.FacebookAdsApi.init(accessToken);
### Api main class
The FacebookAdsApi object is the foundation of the Business SDK which encapsulates the logic to execute requests against the Graph API.
Once instantiated, the Api object will allow you to start making requests to the Graph API.

Facebook Objects
Facebook Ads entities are defined as classes under the src/objects directory.javascript
// instantiating an object
const adsSdk = require('facebook-nodejs-business-sdk');
const AdAccount = adsSdk.AdAccount;
const account = new AdAccount('act_');
console.log(account.id) // fields can be accessed as properties
### Fields
Due to the high number of field names in the existing API objects, in order to facilitate your code maintainability, enum-like field objects are provided within each node class.
The fields are stored within node object classes which are stored under the src/objects directory.
You can access object properties like this:javaScript
const adsSdk = require('facebook-nodejs-business-sdk');
const accessToken = '';
const api = adsSdk.FacebookAdsApi.init(accessToken);
const AdAccount = adsSdk.AdAccount;
const Campaign = adsSdk.Campaign;
const account = new AdAccount('act_');
console.log(account.id) // fields can be accessed as properties
account
  .createCampaign(
    [Campaign.Fields.Id],
    {
      [Campaign.Fields.name]: 'Page likes campaign', // Each object contains a fields map with a list of fields supported on that object.
      [Campaign.Fields.status]: Campaign.Status.paused,
      [Campaign.Fields.objective]: Campaign.Objective.page_likes
    }
  )
  .then((result) => {
  })
  .catch((error) => {
  });
#### Read Objectsjavascript
const adsSdk = require('facebook-nodejs-business-sdk');
const accessToken = '';
const api = adsSdk.FacebookAdsApi.init(accessToken);
const AdAccount = adsSdk.AdAccount;
const account = new AdAccount('act_');
account
  .read([AdAccount.Fields.name, AdAccount.Fields.age])
  .then((account) => {
    console.log(account);
  })
  .catch((error) => {
  });
Requesting an high number of fields may cause the response time to visibly increase, you should always request only the fields you really need.
Create Objectsjavascript
const adsSdk = require('facebook-nodejs-business-sdk');
const accessToken = '';
const api = adsSdk.FacebookAdsApi.init(accessToken);
const AdAccount = adsSdk.AdAccount;
const Campaign = adsSdk.Campaign;
const account = new AdAccount('act_');
account
  .createCampaign(
    [],
    {
      [Campaign.Fields.name]: 'Page likes campaign',
      [Campaign.Fields.status]: Campaign.Status.paused,
      [Campaign.Fields.objective]: Campaign.Objective.page_likes
    }
  )
  .then((campaign) => {
  })
  .catch((error) => {
  });
#### Update Objectsjavascript
const adsSdk = require('facebook-nodejs-business-sdk');
const accessToken = '';
const api = adsSdk.FacebookAdsApi.init(accessToken);
const Campaign = adsSdk.Campaign;
const campaignId = ;
new Campaign(campaignId, {
  [Campaign.Fields.id]: campaign.id,
  [Campaign.Fields.name]: 'Campaign - Updated' })
  .update();
#### Delete Objectsjavascript
const adsSdk = require('facebook-nodejs-business-sdk');
const accessToken = '';
const api = adsSdk.FacebookAdsApi.init(accessToken);
const Campaign = adsSdk.Campaign;
const campaignId = ;
new Campaign(campaignId).delete();
### Pagination
Since the release of the Facebook Graph API 2.0, pagination is handled through <a href="https://developers.facebook.com/docs/graph-api/using-graph-api/v2.2#paging" target="_blank">cursors</a>.
Here cursors are defined as in src\cursor.js. When fetching nodes related to another (Edges) or a collection in the graph, the results are paginated in a Cursor class.
Here the Cursor is a superpowered Array (with all it's native helpful operations) with next and previous methods that when resolved fills itself with the new set of objects.javascript
const adsSdk = require('facebook-nodejs-business-sdk');
const accessToken = '';
const api = adsSdk.FacebookAdsApi.init(accessToken);
const AdAccount = adsSdk.AdAccount;
const Campaign = adsSdk.Campaign;
const account = new AdAccount('act_');
account.getCampaigns([Campaign.Fields.name], { limit: 2 })
.then((campaigns) => {
  if (campaigns.length >= 2 && campaigns.hasNext()) {
    return campaigns.next();
  } else {
    Promise.reject(
      new Error('campaigns length < 2 or not enough campaigns')
    );
  }
})
.then((campaigns) => {
  if (campaigns.hasNext() && campaigns.hasPrevious()) {
    return campaigns.previous();
  } else {
    Promise.reject(
      new Error('previous or next is not true')
    );
  }
  return campaigns.previous();
})
.catch((error) => {
});
If you are using cursor to iterate all of your object under your Ad Account, this practice is recommended.javascript
const adsSdk = require('facebook-nodejs-ads-sdk');
const accessToken = '';
const api = adsSdk.FacebookAdsApi.init(accessToken);
const AdAccount = adsSdk.AdAccount;
const account = new AdAccount('act_');
void async function () {
    let campaigns = await account.getCampaigns([Campaign.Fields.name], {limit: 20});
    campaigns.forEach(c => console.log(c.name));
    while (campaigns.hasNext()) {
        campaigns = await campaigns.next();
        campaigns.forEach(c => console.log(c.name));
    }
}();
#### Debugging
A FacebookAdsApi object offers a debugging mode that will log all requests. To enable it just call api.setDebug(true) on an API instance.javascript
const adsSdk = require('facebook-nodejs-business-sdk');
const accessToken = '';
const api = adsSdk.FacebookAdsApi.init(accessToken);
api.setDebug(true);
### Style
This package uses type safe javascript. <a href="https://flow.org/" target="_blank">Flow</a>. Inconsistent code will break builds.
Conversions API
The Business SDK includes a server-side client for the Conversions API, used to send web, app, and offline events to Meta directly from your server.js
const bizSdk = require('facebook-nodejs-business-sdk');
const ServerEvent = bizSdk.ServerEvent;
const EventRequest = bizSdk.EventRequest;
const UserData = bizSdk.UserData;
const CustomData = bizSdk.CustomData;
bizSdk.FacebookAdsApi.init('');
const userData = (new UserData())
  .setEmail('[email protected]')
  .setClientIpAddress(request.connection.remoteAddress)
  .setClientUserAgent(request.headers['user-agent']);
const customData = (new CustomData())
  .setCurrency('usd')
  .setValue(123.45);
const serverEvent = (new ServerEvent())
  .setEventName('Purchase')
  .setEventTime(Math.floor(Date.now() / 1000))
  .setUserData(userData)
  .setCustomData(customData)
  .setEventSourceUrl('http://jaspers-market.com/product/123')
  .setActionSource('website');
const response = await (new EventRequest('', ''))
  .setEvents([serverEvent])
  .execute();
console.log(response);
For advanced features — asynchronous requests, concurrent batching, and a custom HTTP service — see Meta Business SDK Features for Conversions API.
Conversions API Parameter Builder integration
The SDK bundles the Conversions API Parameter Builder (NodeJS README) so it can auto-fill key event parameters straight from the incoming HTTP request. Call setRequestContext() on an event and pass the incoming request — see Framework support for exactly what to pass for your framework (e.g. a Node http.IncomingMessage, or an Express/Fastify/Koa/NestJS request). At send time the SDK runs the Parameter Builder and fills in any of these fields you left empty:

user_data.fbc, user_data.fbp, user_data.client_ip_address

event_source_url, referrer_urljsconst Preference = bizSdk.Preference;
const serverEvent = (new ServerEvent())
  .setEventName('Purchase')
  .setEventTime(Math.floor(Date.now() / 1000))
  .setUserData((new UserData()).setEmail('[email protected]'))
  .setActionSource('website')
  .setRequestContext(request);

// Optional: gate which fields may be auto-filled (all default true). // Order: fbc, fbp, client_ip_address, referrer_url, event_source_url. // .setRequestContext(request, new Preference(true, true, true, true, false));`

Auto-fill is gated by the optional Preference allowlist, non-destructive (a value you set yourself is never overwritten), and order-independent. In NodeJS, UserData` customer-information parameters (email, phone, etc.) are also normalized and SHA-256 hashed automatically via the Parameter Builder, following Meta's best practices.

SDK Codegen

Our SDK is autogenerated from SDK Codegen. If you want to learn more about how our SDK code is generated, please check this repository.

Join the Facebook Marketing Developer community

Website: https://www.facebook.com/groups/pmdcommunity
Facebook page: https://www.facebook.com/marketingdevelopers/

See the CONTRIBUTING file for how to help out.

License

Facebook Business SDK for NodeJS is licensed under the LICENSE file in the root directory of this source tree.

meta/facebook-nodejs-business-sdk: Node.js SDK for Meta Marketing APIs

Facebook Business SDK for NodeJS

Introduction

Quick Start

Pre-requisites

Dependencies

Register An App

Obtain An Access Token

Installation

Usage

Access Token

Facebook Objects

`Create Objects`

Conversions API

Conversions API Parameter Builder integration

SDK Codegen

Join the Facebook Marketing Developer community

License

Reading Mode

Related Stories

Ashby (YC W19) Is Hiring EMs

Sava Trust (YC F25) Is Hiring a Founding Engineer in NYC

No Vehicles in the Park

Bitmovin (YC S15) Is Hiring Technical Graduates in Denver (Engineering/CS Focus)

Why are Soviet math textbooks so hardcore in comparison to US textbooks? (2017)

Related Stories