1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
|
twitter-event-stream
====================
*WORK IN PROGRESS: My application for a developer account has not yet been
approved and the code is not tested at all.*
Description
-----------
twitter-event-stream provides an HTTP long polling endpoint that works in a
similar way to the deprecated User Streams API[1]. It uses the REST API and
the Account Activity API.
It is no easy work to update a Twitter client application built on top of the
User Streams API. Even worse, the Account Activity API which pretends to be
the replacement cannot be used directly by a mobile Twitter client.
twitter-event-stream allows such applications to continue to work with the
minimal amount of changes.
[1] https://twittercommunity.com/t/details-and-what-to-expect-from-the-api-deprecations-this-week-on-august-16-2018/110746
Setup
-----
Configuration
~~~~~~~~~~~~~
- You have to gain access to (the premium version of) the Account Activity
API. A whitelisted consumer key and the consumer secret are specified by
environment variables.
TWITTER_EVENT_STREAM_CONSUMER_KEY=<consumer key>
TWITTER_EVENT_STREAM_CONSUMER_SECRET=<consumer secret>
- Credentials used for fetching home_timeline are stored in environment
variables named `TWITTER_EVENT_STREAM_USER_<tag>`. `<tag>` may be any
text.
TWITTER_EVENT_STREAM_USER_ABC=<value>
`<value>` is a JSON encoding of the following object:
{
"user_id": <user's numerical id>,
"requests_per_window": 15,
"token": <access token>,
"token_secret": <access token secret>
}
# Increase requests_per_window if your application is granted the
# permission to make more requests per 15 minutes window.
If you need to use a different consumer key pair for the REST API requests,
add the following to the JSON object. The token may be read-only.
{
"rest_consumer_key": <consumer key>,
"rest_consumer_secret": <consumer secret>,
"rest_token": <access token>,
"rest_token_secret": <access token secret>,
}
NOTE: `setup-oauth.rb` included in this distribution might be useful to
do 3-legged OAuth and make the JSON object.
Deployment
~~~~~~~~~~
- Ruby and Bundler are the prerequisites.
- Install dependencies by `bundle install`, and then run
`bundle exec puma -e production -p $PORT`.
* The quickest way to deploy twitter-event-stream would be to use Heroku.
Click the link and fill forms: https://heroku.com/deploy
- Run `setup-webhook.rb` to register a webhook and perform the Challenge
Response Check required to activate it. The web application must be
already started. Note that `setup-webhook.rb` also requires the
environment variables to be set correctly.
* twitter-event-stream will receive webhooks at /webhook.
Usage
-----
twitter-event-stream opens two endpoints for a client:
- /1.1/user.json
The message format is almost identical to the User streams' message format.
However, due to the limitation of the Account Activity API, direct messages
and some of the event types are not supported.
- /stream
Sends events and home_timeline tweets in the server-sent events format
(text/event-stream). Events have the structure:
event: <event>\r\n
data: <payload>\r\n\r\n
`<event>` will be one of the event types received by the webhook:
* `favorite_events` (for example; see Twitter's documentation[2])
event: favorite_events\r\n
data: [{"id":"...","favorited_status":{...}}]\r\n\r\n
Or, one of the following event types defined by twitter-event-stream:
* `twitter_event_stream_home_timeline`
New items in the home timeline. `<payload>` is an array of Tweet object.
event: twitter_event_stream_home_timeline\r\n
data: [{"id":...,"text":"..."},...]\r\n\r\n
* `twitter_event_stream_message`
A message from twitter-event-stream, such as error reporting. `<payload>`
is a String.
event: twitter_event_stream_message\r\n
data: "Message"\r\n\r\n
Note that comment events are also sent every 30 seconds to keep the HTTP
connection open:
:\r\n\r\n
twitter-event-stream uses "OAuth Echo"[3] to authenticate a client, meaning
an application must provide the following HTTP headers:
- `x-auth-service-provider`
Must be set to
"https://api.twitter.com/1.1/account/verify_credentials.json".
- `x-verify-credentials-authorization`
The content of the Authorization HTTP header that the client would
normally send when calling the account/verify_credentials API.
[2] https://developer.twitter.com/en/docs/basics/authentication/overview/oauth-echo.html
[3] https://developer.twitter.com/en/docs/accounts-and-users/subscribe-account-activity/guides/account-activity-data-objects
License
-------
twitter-event-stream is licensed under the MIT license. See COPYING.
|
