Access Ads On The Facebook Graph API

[karthicks]

More often than not, the Facebook Graph API is used to access users, statuses, events and what-not. In addition, it comes with a Ads API that specifically deals with ads, which can be used to "automate the creation of ads campaigns on Facebook, as well as measure the performance of ad campaigns".

Herein, we propose extending the Spring Social Facebook project to handle Facebook Ads through the Graph API (as opposed to their legacy REST API), by leveraging the existing framework that's already in place. In particular, we'll talk about the abstract models and operations, followed by their concrete template and format definitions. Last but not the least, we'll go into certain generic features that we feel belong in the Graph API layer.

• Ad API Objects: At the top-level, we need Java objects corresponding to the AdAccount, AdAccountGroup, AdCampaign, AdCreative and AdGroup Graph API objects. While most of the fields are primitive types, some reference embedded objects such as User, Stats, etc, not to mention enumerations such as AccountStatus, BidType, Permission and UserRole.
• Ad API Operations: At the top-level, we define a FacebookAds interface, which along the lines of the Facebook interface, is broken down into sub-APIs corresponding to AccountOperations, AccountGroupOperations, CampaignOperations, CreativeOperations, and AdGroupOperations. Most of those operations allow fetching, updating and deleting the underlying object type. In addition, some let you do things like fetch statistics, estimate reach, etc.
• Ad Operation Templates: At the top-level, we implement the aforementioned operations as a FacebookAdsTemplate, much like the FacebookTemplate. The object-specific templates, viz., AccountTemplates, AccountGroupTemplates, CampaignTemplates, CreativeTemplates and AdGroupTemplates delegate most of the work to the underlying graphApi object.
• Ad Object Formats: For the most part, the JSON objects the Graph API understands map directly to the POJO properties. However, there are some cases where the field names did not match, and other cases where a custom deserializer is called for. In order to make the mapping of the Java to JSON objects seamless, we introduced certain Jackson mixin classes.
• Graph API Extensions: Considering that most Graph API objects, including the ad-specific ones, are connected to each other, we felt compelled to extend the GraphAPI interface to handle additions and deletions of connections. In addition, we added a way to update a Graph API object (that unlike the publish method does not require a connection object). Moreover, we implemented a ConnectionTemplate abstract class, which serves as the base class for all of the ad operation templates above.

The goal of the patch that will follow is primarily to (a) serve as a starting point (b) invite inputs on design approach and (c) allow the community at large to work on this together. In other words, this is a work in progress.

[willtaylor]

I didn't see this until submitting my pull request for what appears to be a subset of nearly the same functionality. I'm interested in digging into this code to see your approach.

[karthicks]

Hi Will Taylor,

I'd appreciate your comments on the approach taken here, which is very much along the lines of the existing social template. The code can be broken down into pieces that define:

• the model and sub-interfaces in a "ads"-specific package
• the templates for those "ads" sub-interfaces
• the mixins to translate the "ads" JSON to POJO objects, and
• the top-level template that contains the "ads" sub-templates.

In addition, I added some new functionality in the core API to:

• allow for search and connection operations
• be able to read all kinds of the post objects properly
• allow reads of posts from the page operation

I haven't dug into your code in detail, but I like the fact that you use mock JSON objects for testing. I, on the other hand, make my test case hit the Facebook Ads API directly. While I haven't been able to automate that part yet (since it requires a whitelisted valid access token and account id), it helps ensure that there's no gap between the client and their server. Not sure what the right testing approach should be.

At any rate, please take a look at the code (and I yours), and hopefully, we can put together something that Craig will find acceptable.

Best Regards,
Karthick Sankarachary

[karthicks]

Just an update, the features in this pull request have been more or less fleshed out. Note that it includes certain generic (i.e., not specific to ads) features, such as search operations, connection operations, page post retrievals, image uploads, among other things. I look forward to your comments and suggestions.

[willtaylor]

Hi Karthick. I was on vacation last week and am just getting back to work and getting caught up. I hope to have some time to look into your code in the next few days and continue this discussion. Thanks!

[ericridge]

Hi Karthick. It looks like this pull request was not picked up. Any idea why?

[habuma]

Eric: Put simply, it wasn't picked up because I've been otherwise engaged for the past several months and haven't had opportunity to review it and merge it into Spring Social Facebook. But I am actively working on some updates for Spring Social (Core|Facebook|Twitter) right now to be part of 1.1.0.M1 (hopefully in time for S2GX in October). This pull request is scheduled to be merged in for 1.1.0.M2 which will naturally follow the M1 release.

[ericridge]

Hi Craig! We've done a lot of work internally at my company on the Ads API within an internally-forked version of spring-social-facebook.

Is it possible for us to have an offline conversation to discuss how we might get our changes merged in? It's not exactly compatible with karthicks' work, and not exactly compatible with willtaylor's work either (although it is based on Will's work).

[habuma]

Eric: I'll be happy to consider any pull request. Feel free to submit it as a pull request on GitHub and I'll try to find a time to review it and merge it in for Spring Social Facebook 1.1.0.

Be aware, however, that while I hope to get Ads API covered for Spring Social Facebook 1.1.0, it's not one of the higher priority items right now and I've got an already ambitious list of things to attack for 1.1.0.M1. And I am aiming to release 1.1.0.M1 in time for SpringOne/2GX in the middle of October. The one thing that will keep that from happening is that I also have a couple of presentations that I must finish preparing for S2GX, so I have to cleverly budget my time. But I'm still hopeful that I can cut some form of 1.1.0.M1 release around the S2GX timeframe.

Here's how to increase the likelihood that your pull request will be merged sooner rather than later:

1. Make sure the code you submit is adequately covered with unit-tests, preferably using Spring Test MVC in the same way the other parts of Spring Social Facebook are tested.
2. Make sure the code mimics the coding style used in the rest of Spring Social.
3. Ideally, it should have minimal or no impact on any other portion of Spring Social.
4. Assure me that, to the best of your knowledge, that the code your submitting does in fact work against the Facebook Ads API.

The more stuff from this list that you are missing requires more work on my part to review and build tests around the pull request before merging it...and with the other stuff in my queue, I'll likely just set your pull request aside until I have more time.

[habuma]

Eric (and anyone else who wants to contribute): Another thing to help move this along is to sign the contributor agreement at https://support.springsource.com/spring_committer_signup if you've not done so already. It makes the legal-minded people around here happy and makes my job easier in case they ask about it.

[seanlai]

Any update on merging ads api?

[Yachironi]

Hi guys,
I've been wondering if this feature (Ads API) has been integrated into latest releases ?
Many thanks for considering my question.

[pivotal-issuemaster]

@karthicks Please sign the Contributor License Agreement!

Click here to manually synchronize the status of this Pull Request.

See the FAQ for frequently asked questions.