T1112 twitter v2 documentation

docs/collections.rst

@@ -9,25 +9,94 @@ Reading the social media platform's documentation provides further important
 details.
 
 Collection types
-  * `Twitter user timeline`_: Collect tweets from specific Twitter accounts
-  * `Twitter search`_: Collects tweets by a user-provided search query from recent tweets
-  * `Twitter sample`_: Collects a Twitter provided stream of a subset of all tweets in real
-    time.
-  * `Twitter filter`_: Collects tweets by user-provided criteria from a stream of
-    tweets in real time.
+
+  * `Twitter user timeline (v. 2)`_: Collect tweets from specific Twitter accounts.
+  * `Twitter search (v. 2)`_: Collect tweets by a user-provided search query from recent tweets.
   * `Flickr user`_: Collects posts and photos from specific Flickr accounts
   * `Weibo timeline`_: Collects posts from the user and the user's friends
   * `Weibo search`_: Collects recent weibo posts by a user-provided search query
   * `Tumblr blog posts`_: Collects blog posts from specific Tumblr blogs
 
-.. _guide-twitter-user-timelines:
+Deprecated collection types
 
-.. _Twitter user timeline:
+As of April 29, 2023, new collections of these types have been deprecated, due to changes in the Twitter API.
+
+  * `Twitter user timeline`_: Collect tweets from specific Twitter accounts. **Deprecated**
+  * `Twitter search`_: Collects tweets by a user-provided search query from recent tweets. **Deprecated**
+  * `Twitter sample`_: Collects a Twitter provided stream of a subset of all tweets in real. **Deprecated**
+    time.
+  * `Twitter filter`_: Collects tweets by user-provided criteria from a stream of
+    tweets in real time. **Deprecated**
+
+.. _guide-twitter-user-timeline-2:
+
+.. _Twitter user timeline (v. 2):
+
+----------------------------
+Twitter user timeline (v. 2)
+----------------------------
+
+Twitter user timeline collections collect the 3,200 most recent tweets from each of
+a list of Twitter accounts using `Twitter's user_timeline API
+<https://developer.twitter.com/en/docs/twitter-api/tweets/timelines/introduction>`_.
+
+**Seeds** for Twitter user timelines are individual Twitter accounts.
+
+To identify a user timeline, you can provide a screen name
+(the string after @, like NASA for @NASA)
+or Twitter user ID (a numeric string which never changes, like 11348282 for
+@NASA). If you provide one identifier, the other will be looked up and displayed
+in SFM the first time the harvester runs. The user may change the screen name
+over time, and the seed will be updated accordingly. 
+
+The harvest schedule should depend on how prolific the Twitter users are.
+In general, the more frequent the tweeter, the more frequent you’ll want to
+schedule harvests.
+
+SFM will notify you when incorrect or private user timeline seeds are requested;
+all other valid seeds will be collected.
+
+See :ref:`guide-incremental-collecting` to decide whether or not to collect
+incrementally.
+
+.. _guide-twitter-search-2:
+
+.. _Twitter search (v. 2):
 
 ---------------------
-Twitter user timeline
+Twitter search (v. 2)
 ---------------------
 
+Twitter searches collect tweets from the last 7-9 days that match search
+queries, similar to a regular search done on Twitter, using
+the `Twitter Search API <https://developer.twitter.com/en/docs/twitter-api/tweets/search/introduction>`__.
+This is **not** a complete search of all tweets; results are limited
+both by time and arbitrary relevance (determined by Twitter).
+
+Search queries must follow the guidelines described in the Twitter documentation for `Building queries for Search Tweets <https://developer.twitter.com/en/docs/twitter-api/tweets/search/api-reference/get-tweets-search-recent>`_.
+
+In SFM, each Twitter search (v. 2) collection can contain only one seed (query), though this may be a complex Boolean query. 
+
+In creating the seed, you can also specify an upper limit (in number of Tweets). This technique is useful given the low monthly cap on data retrieval with Basic access.
+
+In choosing a schedule for your Twitter v. 2 collection, make sure to leave enough time between
+searches. (If there is not enough time between searches, later harvests will
+be skipped until earlier harvests complete.) In some cases, you may only
+want to run the search once and then turn off the collection.
+
+See :ref:`guide-incremental-collecting` to decide whether or not to collect
+incrementally.
+
+Only one active seed can be used per search collection. If you need to run multiple searches in parallel, create a new collection for each search, each with a single seed.
+
+.. _guide-twitter-user-timelines:
+
+.. _Twitter user timeline:
+
+----------------------------------
+Twitter user timeline (DEPRECATED)
+----------------------------------
+
 Twitter user timeline collections collect the 3,200 most recent tweets from each of
 a list of Twitter accounts using `Twitter's user_timeline API
 <https://developer.twitter.com/en/docs/tweets/timelines/api-reference/get-statuses-user_timeline.html>`_.
@@ -55,9 +124,9 @@ incrementally.
 
 .. _Twitter search:
 
----------------
-Twitter search
----------------
+---------------------------
+Twitter search (DEPRECATED)
+---------------------------
 
 Twitter searches collect tweets from the last 7-9 days that match search
 queries, similar to a regular search done on Twitter, using
@@ -88,9 +157,9 @@ Only one active seed can be used per search collection. If you need to run multi
 
 .. _Twitter sample:
 
---------------
-Twitter sample
---------------
+---------------------------
+Twitter sample (DEPRECATED)
+---------------------------
 
 Twitter samples are a random collection of approximately 0.5--1% of public
 tweets, using the `Twitter sample stream
@@ -109,9 +178,9 @@ Only one sample or :ref:`Twitter filter` can be run at a time per credential.
 
 .. _Twitter filter:
 
----------------
-Twitter filter
----------------
+---------------------------
+Twitter filter (DEPRECATED)
+---------------------------
 
 Twitter Filter collections harvest a live selection of public tweets from
 criteria matching keywords, locations, languages, or users, based on the

docs/conf.py

@@ -55,7 +55,7 @@
 # built documents.
 #
 # The full version, including alpha/beta/rc tags.
-release = '2.5.0'
+release = '3.0.0'
 # The short X.Y version.
 version = release[0:release.rindex(".")]
 

docs/credentials.rst

@@ -54,29 +54,14 @@ Accounts section of the Admin interface.
 Adding Twitter Credentials
 --------------------------
 
-As a user, the easiest way to set up Twitter credentials is to connect them to your
-personal Twitter account or another Twitter account you control. If you want
-more fine-tuned control, you can manually set up application-level credentials
-(see below). To connect Twitter credentials, first sign in to Twitter with the account 
-you want to use. Then, on the Credentials page, click *Connect to Twitter*. Your browser will open a page from Twitter, asking you for authorization. Click *Authorize*,
-and your credentials will automatically connect. Once credentials are connected, 
-you can start :ref:`guide-creating-collections`.
-
-Twitter application credentials can be obtained from `the Twitter API
-<https://developer.twitter.com/apps>`_. This process requires applying for
-a developer account for your organization or your personal use and describing
-your use case for SFM. Be sure to answer all of the questions in the
-application. You may receive email follow-up requesting additional 
-information before the application is approved.
-
-Creating application credentials and manually adding Twitter credentials, 
-rather than connecting them automatically
-using your Twitter account (see above), gives you greater control over your
-credentials and allows you to use multiple credentials.
+To harvest data from the Twitter API as of April 29, 2023, it is necessary to sign up **and pay for** `Basic access <https://developer.twitter.com/en/portal/products/basic>`_. (The "Free" access tier does not permit users to retrieve Tweets via API, only to publish them.)
+
+Due to the low monthly limits on data retrieval imposed by Twitter (10K Tweets per month, as of 4/29/2023), each SFM user should obtain their own API credentials. 
 
 To obtain application credentials:
   * Navigate to `<https://developer.twitter.com/en/apply-for-access>`_.
-  * Sign in to Twitter.
+  * Sign in to Twitter, or create an account if you don't already have one.
+  * Once you are logged into the Twitter Developer Portal, you can click the **Upgrade** button to upgrade your account to Basic Access.
   * Follow the prompts to describe your intended use case for academic research. 
   * When a description for your app is requested, you may include:
     *This is an instance of Social Feed Manager, a social media research and 
@@ -89,25 +74,15 @@ To obtain application credentials:
   * It is recommended to change the application permissions to read-only.
   * **Review and agree to the Twitter Developer Agreement**.
 
-You may need to wait several days for the account and app to be approved. One 
-approved, it is recommended that you:
-  * Click on your new application.
-  * Navigate to the *Permissions* tab.
-  * Select *Read only* then *Update settings*.
-
-You now have application-level credentials you can use in your ``.env`` file.
-
 To manually add a Twitter Credential in your SFM user account:
-  * **Go to the Credentials page of SFM,** and click *Add Twitter Credential*.
-  * Fill out all fields:
-      * On the Twitter apps page (https://apps.twitter.com/) click your new
-        application.
-      * Navigate to the *Keys and Access Tokens* tab.
-      * From the top half of the page, copy and paste into the matching fields
-        in SFM: *Consumer Key* and *Consumer Secret*.
-      * From the bottom half of the page, copy and paste into the matching
-      fields in SFM: *Access Token* and *Access Token Secret*.
-  * **Click** *Save*
+  * Go to the Credentials page of SFM, and click `Add Twitter2 Credential`.
+  * There are two ways of saving your credentials in SFM:
+      1. Enter an `API key`, `API key secret`, `Access token`, and `Access token secret`.
+      2. Or enter a `Bearer token` (recommended).
+  * To obtain your credentials, visit the `Twitter Developer Portal Dashboard <https://developer.twitter.com/en/portal/dashboard>`_ and select your project. Under the `Apps` section, click on the key icon to access the `Keys and tokens` menu.
+  * Generate the credentials needed (either the API key/secret and Access token/secret, or the Bearer token).
+  * Save these keys, tokens, and secrets somewhere secure.
+  * Enter the credentials in the Twitter2 Credential form on SFM, and click `Save`.
 
 .. _flickr-credentials: