@denimlabs/facebook-graph-utils

facebook-graph-utils

A collection of composable utilities to make it easier to consume data from facebook graph and APIs

Getting Started

yarn add facebook-graph-utils

Prerequisites

None

Installing

import FBGraphUtilsFactory from 'facebook-graph-utils'
const FBGraphUtils = FBGraphUtilsFactory('TOKEN', 'APPSECRET')

Methods

1. FBGraphUtils.getAllFbApiData: Recursively resolve all Facebook graph data as an array. -- Note: the appsecretProof is auto generated and injected from the factory instantiation. -- Note: If the Graph returns with a next parameter this method will call fb again and concat all of the data recursively until no next is returned. -- ex:

   FBGraphUtils.getAllFbApiData('https://graph.facebook.com/v2.10/act_ACCOUNT_ID/insights')
   .then(console.log)

1. FBGraphUtils.objectToGetParamsShallow: Turn POJO into get params -- ex:

    console.log(FBGraphUtils.objectToGetParamsShallow({a:1,b:2}))
    //a=1&b=2

1. FBGraphUtils.generateAppsecretProof: return appsecret proof -- ex:

    const appSecretProof = FBGraphUtils.generateAppsecretProof('token', 'appsecret')

1. FBGraphUtils.execute: helper to get all data from endpoint w/ params. Also fixes any act_ id issues.

import FBGraphUtilsFactory from 'facebook-graph-utils'
const FBGraphUtils = FBGraphUtilsFactory('TOKEN', 'APPSECRET')

FBGraphUtils
    .setLevel('campaign')
    .setInsightsFields()
    .setBreakdowns('publisher_platform, platform_position, impression_device')
    .setInsightsEndpoint()
    .setApiId('CAMPAIGN_ID_HERE')
    .execute()
    .then(console.log)

BaseParam Helper

Returns a params object with helper methods attached for crafting FB Graph query strings. Note that using this helper module will automatically inject appsecretproof and token into your get parameters as needed for consuming data on the FB Graph API. As of v1.0.10 this is included on the base FBGraphUtils, but can be called standalone by using BaseParamFactory

Methods

1. FBGraphUtils.setActionBreakdowns: sets the action breakdowns parameter
2. FBGraphUtils.setBreakdowns: sets the breakdowns parameter
3. FBGraphUtils.setDatePreset: sets the date preset parameter (defaults lifetime)
4. FBGraphUtils.setInsightsFields: sets the fields parameter to all available insights fields
5. FBGraphUtils.setCampaignFields: sets the fields parameter to all available campaign fields
6. FBGraphUtils.setAdFields: sets the fields parameter to all available ad fields
7. FBGraphUtils.setAdSetFields: sets the fields parameter to all available ad set fields
8. FBGraphUtils.setAdCreativeFields: sets the fields parameter to all available creative fields
9. FBGraphUtils.setActivityFields: sets the fields parameter to all available activity fields
10. FBGraphUtils.setAdImageFields: sets the fields parameter to all available ad image fields
11. FBGraphUtils.setFields: explicitly sets the fields parameter
12. FBGraphUtils.setLevel: sets the level parameter
13. FBGraphUtils.setLimit: sets the limit parameter (defaults 50)
14. FBGraphUtils.toGetParams: converts this object to usable get params

apiParams Example

import FBGraphUtilsFactory from 'facebook-graph-utils'
const FBGraphUtils = FBGraphUtilsFactory('TOKEN', 'APPSECRET')
const campaignBreakdownInsightsParams =
    FBGraphUtils
    .setLevel('campaign')
    .setInsightsFields()
    .setBreakdowns('publisher_platform, platform_position, impression_device')
    .toGetParams()

//?appsecret_proof=XXXXX&access_token=TOKEN&date_preset=lifetime&limit=50&level=campaign&fields=ad_id ,account_currency,account_id,account_name,action_values,actions,ad_name,adset_id,adset_name,buying_type,call_to_action_clicks,campaign_id,campaign_name,canvas_avg_view_percent,canvas_avg_view_time,canvas_component_avg_pct_view,clicks,cost_per_10_sec_video_view,cost_per_action_type,cost_per_estimated_ad_recallers,cost_per_inline_link_click,cost_per_inline_post_engagement,cost_per_outbound_click,cost_per_total_action,cost_per_unique_action_type,cost_per_unique_click,cost_per_unique_inline_link_click,cost_per_unique_outbound_click,cpc,cpm,cpp,ctr,date_start,date_stop,estimated_ad_recall_rate,estimated_ad_recallers,frequency,impressions,inline_link_click_ctr,inline_link_clicks,inline_post_engagement,mobile_app_purchase_roas,objective,outbound_clicks,outbound_clicks_ctr,place_page_name,reach,relevance_score,social_clicks,social_impressions,social_reach,social_spend,spend,total_action_value,total_actions,total_unique_actions,unique_actions,unique_clicks,unique_ctr,unique_inline_link_click_ctr,unique_inline_link_clicks,unique_link_clicks_ctr, unique_outbound_clicks,unique_outbound_clicks_ctr,unique_social_clicks,video_10_sec_watched_actions,video_15_sec_watched_actions,video_30_sec_watched_actions,video_avg_percent_watched_actions,video_avg_time_watched_actions,video_p100_watched_actions,video_p25_watched_actions, video_p50_watched_actions,video_p75_watched_actions,video_p95_watched_actions,website_ctr,website_purchase_roas&breakdowns=publisher_platform, platform_position, impression_device
FBGraphUtils.getAllFbApiData(`https://graph.facebook.com/v2.10/CAMPAIGN_ID_HERE/insights${campaignBreakdownInsightsParams}`)
.then(console.log)

ApiEndpointUtils Helper

Returns an endpoint object with helper methods attached for crafting FB Graph urls. Note: as of v1.0.10 this is included on the base FBGraphUtils but can be used seperately by using makeApiEndpointUtils

Methods

1. FBGraphUtils.setEndpoint: sets the endpoint in url explicitly
2. FBGraphUtils.setInsightsEndpoint: sets the endpoint to '/insights'
3. FBGraphUtils.setCampaignsEndpoint: sets the endpoint to '/campaigns'
4. FBGraphUtils.setAdsetsEndpoint: sets the endpoint to '/adsets'
5. FBGraphUtils.setAdsEndpoint: sets the endpoint to '/ads'
6. FBGraphUtils.setActivitiesEndpoint: sets the endpoint to '/activities'
7. FBGraphUtils.setAdImagesEndpoint: sets the endpoint to '/adimages'
8. FBGraphUtils.setTransactionsEndpoint: sets the endpoint to '/transactions'
9. FBGraphUtils.setSearchEndpoint: sets the endpoint to '/search'
10. FBGraphUtils.setApiId: sets the ID to be used in the query
11. FBGraphUtils.getApiEndpoint: gets the endpoint containing base, version, id (if present), endpoint and params (if passed in)
12. FBGraphUtils.setApiVersion: sets the api version explicitly

apiEndpointUtils Example

//Note this is just an illustration, it's recomended to compose and use execute (see above example for execute)
import FBGraphUtilsFactory from 'facebook-graph-utils'
const FBGraphUtils = FBGraphUtilsFactory('TOKEN', 'APPSECRET')
const campaignBreakdownInsightsParams =
    FBGraphUtils
    .setLevel('campaign')
    .setInsightsFields()
    .setBreakdowns('publisher_platform, platform_position, impression_device')
    .toGetParams()

const campaignInsightsEndpoint =
    FBGraphUtils
    .setInsightsEndpoint()
    .setApiId('CAMPAIGN_ID_HERE')
    .getApiEndpoint(campaignBreakdownInsightsParams)

//https://graph.facebook.com/v2.10/CAMPAIGN_ID_HERE/insights?appsecret_proof=XXXXX&access_token=TOKEN&date_preset=lifetime&limit=50&level=campaign&fields=ad_id ,account_currency,account_id,account_name,action_values,actions,ad_name,adset_id,adset_name,buying_type,call_to_action_clicks,campaign_id,campaign_name,canvas_avg_view_percent,canvas_avg_view_time,canvas_component_avg_pct_view,clicks,cost_per_10_sec_video_view,cost_per_action_type,cost_per_estimated_ad_recallers,cost_per_inline_link_click,cost_per_inline_post_engagement,cost_per_outbound_click,cost_per_total_action,cost_per_unique_action_type,cost_per_unique_click,cost_per_unique_inline_link_click,cost_per_unique_outbound_click,cpc,cpm,cpp,ctr,date_start,date_stop,estimated_ad_recall_rate,estimated_ad_recallers,frequency,impressions,inline_link_click_ctr,inline_link_clicks,inline_post_engagement,mobile_app_purchase_roas,objective,outbound_clicks,outbound_clicks_ctr,place_page_name,reach,relevance_score,social_clicks,social_impressions,social_reach,social_spend,spend,total_action_value,total_actions,total_unique_actions,unique_actions,unique_clicks,unique_ctr,unique_inline_link_click_ctr,unique_inline_link_clicks,unique_link_clicks_ctr, unique_outbound_clicks,unique_outbound_clicks_ctr,unique_social_clicks,video_10_sec_watched_actions,video_15_sec_watched_actions,video_30_sec_watched_actions,video_avg_percent_watched_actions,video_avg_time_watched_actions,video_p100_watched_actions,video_p25_watched_actions, video_p50_watched_actions,video_p75_watched_actions,video_p95_watched_actions,website_ctr,website_purchase_roas&breakdowns=publisher_platform, platform_position, impression_device
FBGraphUtils.getAllFbApiData(campaignInsightsEndpoint)
.then(console.log)

Extra Configuration

The package uses request-promise, bluebird Promises and CryptoJS by default. Any of these dependencies can be overridden. For example to create the FBGraphUtils using 'request' rather than 'request-promise' you can do the following:

import request from 'request'
import Promise from 'bluebird'
import CryptoJS from 'crypto-js';
import makeFBGraphUtilsFactory from 'facebook-graph-utils/facebook-graph-utils'

const defaultServices = {
    request,
    Promise,
    CryptoJS
  }
const FBGraphUtilsFactory = makeFBGraphUtilsFactory(defaultServices)
const FBGraphUtils = FBGraphUtilsFactory('TOKEN', 'APPSECRET')

Note: the only libraries tested are the default injected services.

Running the tests

yarn test

Deployment

yarn publish

Built With

• node - Node 9.2.0
• babel-cli - Used for transpiling and running es6
• babel-preset-env - Used for transpiling and running es6
• jest - Testing framework
• chai - Assertion Library
• husky - Pre-commit hooks
• lint-staged - Linting for changed files
• fs - node file system module
• chalk - Colored console output
• commitizen - commit log standards
• request-promise - request with Bluebird Promises
• bluebird - Bluebird Promise Library
• CryptoJS - JS crypto library

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

Authors

• Michael W. Clark - Initial work - MichaelWClark

License

(MIT License)

Copyright (c) 2017 Denim® [e-mail]

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.