Introduction
Instagram Graph API provides a consistent way for users to pull social media relevant metrics/data for end user analytics
User Storie(s)
As a user, I would like to retrieve user profile/account data from Instagram so I can use it for end user analytics
As a user, I would like to specify aggregation period and time range for the account metrics so that I can filter the data that I need for my end user analytics
As a user, I would like to retrieve social interaction metrics (image, video, or album) for relevant media objects, so that I can leverage for end user analytics
Plugin Type
Configurables
This section defines properties that are configurable for this plugin.
User Facing Name | Type | Description | Constraints |
|---|---|---|---|
Access token | string | Access token |
|
Request Type | select |
|
|
Account ID | string | Account ID |
Mandatory if Request Type = "Get Account Insights" |
Media ID | string | Media Object ID | Mandatory if Request Type = "Get Media Insights" |
Metrics To Pull | multi-select | Select the list of available fields to pull | The metrics dropdown will change based on the request type. See the links in the design section for the list of available metrics. The schema will change based on the fields selected by the user |
Period | select | Aggregation period/no of days for metric | Mandatory if Request Type = "Get Account Insights" |
From Date | string | Start date for retrieving metric details | Mandatory if Request Type = "Get Account Insights" |
To Date | string | End date for retrieving metric details | Mandatory if Request Type = "Get Account Insights" |
Design / Implementation Tips
Metrics to pull will dynamically change based on the type of request that is selected. Output schema will depend on this selection. https://developers.facebook.com/docs/instagram-api should be used for implementation and data pulls
Account Insights - Fields to Pull
https://developers.facebook.com/docs/instagram-api/reference/user/insights#metrics-periods
Media Insights - Fields to Pull
https://developers.facebook.com/docs/instagram-api/reference/media/insights
Comments
@Vasudha Gupta (Unlicensed) from a cursory look at the documentation of the instagram API, it seems fine to focus on account and media insights for now. If it is possible, I would only add the ability to fetch any insights from Instagram Ads in this flow. Is that possible?
Also, can't this be realtime?
I think in my opinion this is just batch for now. The insights is generating aggregate metrics like impressions, profile views, not sure there is a need to keep getting this insight data on a real time basis. IT would also not really be real time but more like pseudo real time because you would then be polling for changes
@Bhooshan Mogal There is a plugin for Facebook Ads insights. The Insights API used for both Facebook and Instagram is the same. There is a way to distinguish between both using a parameter - details available on this page https://developers.facebook.com/docs/marketing-api/guides/instagramads/ads_management. So if I was to design this - i would re-use the Facebook Ad Insights Plugin - and maybe rename to Ad Insights - with the options to select either Facebook insights or Instagram insights using the user option
As far as I see insights api really the same. Looks like FB plugin can be used as is, since everything depends on what initial account/campaign/ad/ad set ID was passed, no type selection is required. I will try to get some instagram account to test it out.
They are the same , but I saw this statement that made me think that there might be a filter we need to apply, if you check on the page, it is highlighted under Ad Insights
If you are running a campaign on Instagram and Facebook, add breakdowns=publisher_platform to see the stats of Facebook and Instagram placements separately:
I see, nice catch. FB insights plugin already has a choice between all possible combinations of breakdowns in select widget, and publisher_platform is one of them. If we are going to reuse FB Insights plugin as a single plugin for FB and Instagram, we can add some documentation notice about this specific breakdown. Also I think it will be nice to rename entire plugin to something like "Graph Insights" to strictly identify plugin as one that using graph insights api, not some old instagram api that looks different. Same can be applied for plugin icon.
I will read documentation once more again to find out something else that can be interesting in scope of fb+instagram. If we are going to make this common plugin and not separate them, we need to change FB plugin wiki page accordingly and I will make required changes in my pull request.
cc @Bhooshan Mogal
I think its fine.
Let's not rename the FB plugin to Graph plugin. Facebook is much more discoverable to our audience. Graph is very technical.
Let's add documentation in the FB insights plugin to specify how to filter Instagram Ads.
Let's add documentation in the Instagram plugin to call out that it is for the instagram account and media insights. For ads insights, use the Facebook Ads Insights plugin.
Makes sense, thanks for reply.
So Facebook plugin allows to get info related to ads and campaigns. Which Insights should provide Instagram plugin? Only account and media, like it is now described in design document?
Based on the discussion Bhooshan and I had - only Instagram media and account insights should be considered for now
@Bhooshan Mogal - i need a little bit of guidance on this plugin. There are many different kinds of data pull that we could from Instagram, an obvious is account insights for which I have specified the details above. In addition I have also added media insights that allows you to pull details about a media object. But there is a fairly large list of query types a user can potentially do. Do we have any sense of the kind of use cases that we heard about from clients or should I assume to need to support all of them. Can you please let me know your thoughts? i have added the ones in bold that I have accounted for so far.
User level queries:
get insights on an IG User
get all IG Media objects on an IG User
get all story IG Media objects on an IG User
get data on IG Media objects on which an IG User has been tagged
get data on IG Comments on which an IG User has been @mentioned
get data about IG Media objects on which an IG User has been @mentioned in a caption
Media level queries:
get metadata for individual media objects
get all child media objects in an album carousel
get all comments for individual media objects
get all insights for individual media objects
Hastag level queries
a list of media objects recently tagged with this hashtag
a list of the most popular media objects tagged with this hashtag
Comment level queries
get all replies to a comment