Facebook Business SDK for Java

Before making any API calls, you must create an APIContext object. This object holds your authentication credentials, specifically your ACCESS_TOKEN and APP_SECRET.

APIContext context = new APIContext(ACCESS_TOKEN, APP_SECRET);

To modify the SDK and use your changes in a local project:

1. Clone or download the source code and import it into your IDE.
2. Make your modifications.
3. Remove the maven-gpg-plugin defined in the pom.xml.
4. Build and install the package to your local Maven repository using:

   mvn clean install

5. Update your own project's pom.xml to reference your locally modified version (ensure the version number matches if you changed it).

Most edge APIs return a limited number of objects (approx. 30). To access subsequent pages, you can either manually call .nextPage() or enable the auto-pagination iterator.

When using withAutoPaginationIterator(true), the iterator() or enhanced for-loops will automatically fetch new pages. Warning: When auto-pagination is enabled, methods like campaigns.size() and campaigns.get(i) are no longer reliable.

// Manual pagination
campaigns = campaigns.nextPage();

// Auto pagination
campaigns = campaigns.withAutoPaginationIterator(true);
for(Campaign campaign : campaigns) {
    System.out.println(campaign.getFieldName());
}

To inspect network requests and responses, enable debug mode on your APIContext. You can customize the output destination using .setLogger().

APIContext context = new APIContext(ACCESS_TOKEN, APP_SECRET)
    .enableDebug(true)
    .setLogger(System.out);

To reduce network round trips, use BatchRequest to group multiple API calls into a single HTTP request. Instead of calling .execute(), use .addToBatch(batch, "identifier") for each request. Finally, call batch.execute() to send the entire batch.

BatchRequest batch = new BatchRequest(context);

account.createCampaign()
    .setName("Batch Campaign")
    .addToBatch(batch, "campaignRequest");

account.createAdSet()
    .setName("Batch AdSet")
    .setCampaignId("{result=campaignRequest:$.id}")
    .addToBatch(batch, "adsetRequest");

List<APIResponse> responses = batch.execute();

You can install the SDK using Maven or by downloading pre-compiled .jar files.

Maven (Recommended)

Use Maven Central to manage the dependency in your pom.xml.

Manual JAR Installation

If you download a pre-compiled .jar file from Maven Central, ensure you also download all required dependent .jar files. You can use the .pom file located in the version directory to identify the necessary dependencies.

To modify an existing object, use the .update() method followed by the desired setters and .execute(). To remove an object, use .delete().execute().

// Update
campaign.update()
        .setName("Updated Java SDK Test Campaign")
        .execute();

// Delete
campaign.delete().execute();

Before using the SDK, you must complete the following setup on the Facebook Developer Portal:

1. Register an App: Create an app at developers.facebook.com.
2. Add Marketing API: For Marketing API functionality, go to your App Dashboard and add the Marketing API product.
3. Security Recommendation: Enable 'App Secret Proof for Server API calls' in your app's Settings -> Advanced page.
4. Obtain Access Token:
   • Use the Graph Explorer to generate a token for testing.
   • For Marketing API, generate a User access token with the ads_management permission.
   • For Pages API, generate a Page access token with the manage_page permission.

To retrieve an object (e.g., a Campaign), you can either instantiate the object with the ID and context and then call .get(), or use the fetchById shortcut.

Important: All API calls must end with .execute() to be sent to the server. Use .requestAllFields() to get all available data, or .requestXXXFields() to specify a subset of fields.

// Method 1: Manual instantiation and execution
Campaign campaign = new Campaign(CAMPAIGN_ID, context);
campaign = campaign.get().requestAllFields().execute();

// Method 2: Shortcut
Campaign campaign = Campaign.fetchById(CAMPAIGN_ID, context);