A developer’s getting started guide

Developer getting started guide

Introduction

The purpose of this documentation is to provide developers an introduction to integrating with the InsightsTrack API. We’ll start off by discussing the “whys” of integrating, and then start digging into the technical details.

What does the InsightsTrack API provide?

  • The InsightsTrack API is a streaming API that allows developers to receive real-time data on impression and engagement metrics on Tweets.
  • The InsightsTrack API provides impression and engagement data for an authorized and subscribed Twitter account’s Tweets for 7 days after the Tweet is sent. This powerful, yet easy-to-implement solution, gives real time access to impressions and up to 26 different engagement types for subscribed accounts.
  • The InsightsTrack API also provides video quartiles. Video quartiles are metrics that indicate the number of times that 25%, 50%, 75%, 95% and 100% of the video contained in a Tweet was viewed.

Why integrate? Example use-cases

  • Analyze true reach:
    • For the first time at scale, you can analyze unique reach on your Tweets. Reach accounts for unique users viewing a Tweet, even from different devices.
  • Data-driven content recommendations:
    • Analyze time-based signals from how your content performs to make more intelligent recommendations on when to publish.
    • Evaluate objective-specific campaign strategies (e.g., optimizing for video views or link clicks) to determine what to publish.
    • Provide real-time feedback on different creative options to determine the best content to promote.
  • Marketing automation:
    • Alert or notify as soon as a given piece of content crosses a defined engagement threshold so that you can automatically promote it or share it from other accounts.
    • Provide real-time feedback on which media assets perform the best to optimize overall marketing strategy.
    • Empower real-time campaign adjustments.

Now that we’ve explored how the InsightsTrack API solves real problems, let’s start digging into the technical details.

 

Integrating the InsightsTrack API

Introduction to API

The InsightsTrack API is a streaming API that delivers impression and engagement data encoded in JSON. The data that are delivered consists of the following types:

  • Summary objects: provides a cumulative summary of up to 26 different impression and engagement metrics. Summary objects are delivered every 30 seconds based on a Tweet’s creation time, and if the Tweet was created in the last 7 days.
  • Tweets: provides a full Tweet object when a subscribed account sends a Tweet
  • User events: provides an object indicating when a subscribed account has revoked permissions to monitor impression and engagement data

The Engagement API provides two endpoints:

  • Stream endpoint - Connecting to the streaming endpoint consists of a simple GET request using application-only authentication with bearer token credentials. Once a connection is established, data is delivered in JSON format (see sample payload below) through a persistent HTTP streaming connection. You will only receive data from user IDs matching your rules while connected to the stream.
  • Rules endpoint - A separate endpoint managed independently by your application, the rules endpoint supports GET, POST, POST _method=delete and rule validation methods with application-only authentication with bearer token credentials for managing your ruleset. Rules are required to be Twitter user IDs that you would like to track. Up to 1,000 rules can be specified per request and up to 250,000 rules are supported per stream.* The rules endpoint can be accessed, managed, and will persist regardless of your connection status to the stream. ou can also update (add/remove) rules while connected to the stream and the changes will take effect almost immediately.

* This is the maximum number of rules supported, but the number of rules allowed on your stream may vary based on your contract. Please speak with your account manager if you would like to change the number of rules allowed on your stream.

Getting API access

If you are reading this document, you have most likely already obtained access to the InsightsTrack API. If not, please reach out to your account manager, or apply for enterprise access.

The first step is creating a Twitter app using an approved developer account via the developer portal.  Your account manager will need the numeric app ID associated with this application to provide you with access. You can find your app ID in the apps section of your developer portal.

Authentication

InsightsTrack requires the use of HTTPS and application-only OAuth (2.0) with bearer token credentials. For any request, you will need to set up a Twitter application and corresponding API Key using the application management console available at developer.twitter.com. This Application ID will need to be whitelisted by Twitter.

Creating a rule

The good news is that integrating the InsightsTrack API is simple. We can start by adding a rule to begin monitoring the @TwitterDev account for impression and engagement data. The first step is to construct the API request in JSON, consisting of an array of rules. Each rule consists of a key and value pair format. The key is named “value” and the value consists of the keyword “from,” followed by a colon. Following the colon is the user ID of the account that will be subscribed. The user ID can be retrieved from the User object payload returned by passing the screen name of the account to the GET users/show endpoint.

      {
	"rules":
	[
		{"value":"from:2244994945"}
	]
}

We then POST this JSON request to the rules endpoint along with a bearer token. Additionally, we’ll include the following header to indicate that our request is encoded in JSON.

  • Content-Type: application/json

When making requests we authenticate using application-only OAuth (2.0) with bearer token credentials. The API returns a HTTP 201 response code and the following payload to indicate the successful creation of the rule.

      {
  "summary": {
    "created": 1,
    "not_created": 0
  },
  "details": [
    {
      "rule": {
        "value": "from:2244994945",
        "external_rule_id": 1136317191161229314
      },
      "created": true
    }
  ],
  "sent": "Wed Jun 05 17:01:44 +0000 2019"
}

The response includes a summary of the number of rules created and the JSON payload of the actual rule.

Streaming data

After adding a rule to monitor an account for impression and engagement data, our next step is to connect to the streaming endpoint to read data.

curl -v - H "Authorization: Bearer $TOKEN" -H "content-type:application/json" -X GET "https://data-api.twitter.com/stream/insightstrack/accounts/{account-name}/publishers/twitter/{stream-label}.json"

Replace the placeholders for your account name and stream label appropriately. This information can be found in your GNIP console. Once we’ve connected to the stream, data will automatically be delivered every 30 seconds in the form of a summary object. The summary object contains cumulative impression and engagement data, as well as start and end times to indicate when InsightsTrack started and stopped aggregating metrics respectively for a given summary object.

Summary object

      {
    "summary_event": {
        "start_time": "Tue Jan 31 22:22:49 +0000 2017",
        "end_time": "Tue Jan 31 22:50:30 +0000 2017",
        "target": {
            "id": 112233445566778899,
            "id_str": "112233445566778899",
            "user": {
                "id": 123456789123456789,
                "id_str": "123456789123456789"
            }
        },
        "metrics": {
            "impressions": {
                "total": {
                    "count": "12"
                },
                "unique": {
                    "count": "5"
                }
            },
            "engagements": {
                "overall": {
                    "total": {
                        "count": "43"
                    },
                    "unique": {
                        "count": "4"
                    }
                },
                "metric_counts": {
                    "favorites": {
                        "total": {
                            "count": "1"
                        }
                    },
                    "media_clicks": {
                        "total": {
                            "count": "2"
                        }
                    },
                    "video_starts": {
                        "total": {
                            "count": "6"
                        }
                    },
                    "video_viewed_100": {
                        "total": {
                            "count": "5"
                        }
                    },
                    "video_viewed_25": {
                        "total": {
                            "count": "6"
                        }
                    },
                    "video_viewed_50": {
                        "total": {
                            "count": "6"
                        }
                    },
                    "video_viewed_75": {
                        "total": {
                            "count": "6"
                        }
                    },
                    "video_viewed_95": {
                        "total": {
                            "count": "6"
                        }
                    },
                    "video_views": {
                        "total": {
                            "count": "5"
                        }
                    }
                }
            }
        }
    }
}

Summary objects will only be delivered on a stream if the following conditions are met:

  • A Tweet on a subscribed account was engaged or impressed since the last summary object was sent.
  • A Tweet on the subscribed account was created in the last 7 days.
  • The current time coincides with a 30 second interval based on the creation time of the Tweet that was impressed or engaged. For example, if a Tweet was created on June 1, 2019 at 10:00:35 AM, the next update will be sent 30 seconds later at 10:01:05 AM.

If there were no updates to the impression and engagement data among the subscribed accounts, the InsightsTrack API will send new-line keep-alive heartbeats every three seconds. Your application should monitor for these heartbeats to ensure that it is still connected to the stream. A “read data” timeout of 10-15 seconds is recommended for client applications. In the event an account revokes permissions, the InsightsTrack API will send a user_event object. Concurrently, the rule for this account will be automatically deleted and data for this account will no longer be sent on the stream.

User event object

      {
  "user_event": {
    "revoke": {
      "date_time": "2016-10-18T02:16:15.329Z",
      "target": {
        "app_id": 8798497
      },
      "source": {
        "user_id": 760886565136584704
      }
    }
  }
}

Next steps