Show Timelines

Twitter Kit provides Timelines for adding scrollable Search, User, Collection and List Timelines anywhere in your app.

Search Timeline Demo

Note

Timelines can be rendered using user authentication or guest authentication. Also, if you are using a version prior to version 1.10.0 you will need to login as a guest before making the following requests.

Configuration

To show a timeline in your app, configure a timeline data source of your choice e.g. TWTRSearchTimelineDataSource or TWTRUserTimelineDataSource. The list of supported parameters for each timeline can be found in their respective designated initializers. Note that the data source parameters are immutable once set. These parameters will automatically determine the requests it will make on your app’s behalf to the Twitter API to load the previous items.

For example, a TWTRUserTimelineDataSource, which shows the @fabric user’s timeline of Tweets would be built as:

// Objective-C
TWTRAPIClient *client = [[TWTRAPIClient alloc] init];
TWTRUserTimelineDataSource *userTimelineDataSource = [[TWTRUserTimelineDataSource alloc] initWithScreenName:@"fabric" APIClient:client];
// Swift
let client = TWTRAPIClient()
let dataSource = TWTRUserTimelineDataSource(screenName: "fabric", APIClient: client)

and a TWTRSearchTimelineDataSource, which shows Tweets matching “#twitterflock” would be built as:

// Objective-C
TWTRAPIClient *client = [[TWTRAPIClient alloc] init];
TWTRSearchTimelineDataSource *searchTimelineDataSource = [[TWTRSearchTimelineDataSource alloc] initWithSearchQuery:@"#twitterflock" APIClient:client];
// Swift
let client = TWTRAPIClient()
let dataSource = TWTRSearchTimelineDataSource(searchQuery: "#twitterflock", APIClient: client)

Finally, create a TWTRTimelineViewController as the view controller to present the timeline and provide it with the preconfigured <TWTRTimelineDataSource> instance from above. TWTRTimelineViewController will handle loading of Tweets and recycling Tweet views as appropriate.

Showing Actions

To show action buttons you can set the showTweetActions boolean on the TWTRTimelineViewController.

class SearchTimelineViewController: TWTRTimelineViewController {
  convenience init() {
    let client = TWTRAPIClient()
    let dataSource = TWTRSearchTimelineDataSource(searchQuery: "#fabricdev", APIClient: client)
    self.init(dataSource: dataSource)

    // Show Tweet actions
    self.showTweetActions = true
  }
}
Showing Actions

User Timeline

Here’s an example on setting up a User Timeline with TWTRTimelineViewController and TWTRUserTimelineDataSource:

// Objective-C

// FABUserTimelineViewController.h
#import <UIKit/UIKit.h>
#import <TwitterKit/TwitterKit.h>

@interface FABUserTimelineViewController : TWTRTimelineViewController
@end

// FABUserTimelineViewController.m
#import "FABUserTimelineViewController.h"
#import <TwitterKit/TwitterKit.h>
@implementation FABUserTimelineViewController

- (void)viewDidLoad {
  [super viewDidLoad];

  TWTRAPIClient *client = [[TWTRAPIClient alloc] init];
  self.dataSource = [[TWTRUserTimelineDataSource alloc] initWithScreenName:@"fabric" APIClient:client];
}

@end
// Swift

// UserTimelineViewController.swift
import UIKit
import TwitterKit

class UserTimelineViewController: TWTRTimelineViewController {
  override func viewDidLoad() {
      super.viewDidLoad()

      let client = TWTRAPIClient()
      self.dataSource = TWTRUserTimelineDataSource(screenName: "fabric", APIClient: client)
  }
}
User Timeline

As a user scrolls down (finger slides up), previous Tweets will be loaded into the backing UITableView.

Search Timeline

Here’s an example on setting up a Search timeline with TWTRTimelineViewController and TWTRSearchTimelineDataSource:

Note

Search timelines show search results with recent Tweets (~ 1 week) matching a given search query. Check the Search API for information about the advanced search query parameters that can be used in your search query string.

// Objective-C

// FABSearchTimelineViewController.h
#import <UIKit/UIKit.h>
#import <TwitterKit/TwitterKit.h>

@interface FABSearchTimelineViewController : TWTRTimelineViewController
@end

// FABSearchTimelineViewController.m
#import "FABSearchTimelineViewController.h"
#import <TwitterKit/TwitterKit.h>
@implementation FABSearchTimelineViewController

- (void)viewDidLoad {
  [super viewDidLoad];

  TWTRAPIClient *client = [[TWTRAPIClient alloc] init];
  self.dataSource = [[TWTRSearchTimelineDataSource alloc] initWithSearchQuery:@"#twitterflock" APIClient:client];
}

@end
// Swift

// SearchTimelineViewController.swift
import UIKit
import TwitterKit

class SearchTimelineViewController: TWTRTimelineViewController {
    override func viewDidLoad() {
      super.viewDidLoad()

      let client = TWTRAPIClient()
      self.dataSource = TWTRSearchTimelineDataSource(searchQuery: "#twitterflock", APIClient: client)
    }
}
Search Timeline

List Timeline

Here’s an example on setting up a List timeline with TWTRTimelineViewController and TWTRListTimelineDataSource:

// Objective-C

// FABListTimelineViewController.h
#import <UIKit/UIKit.h>
#import <TwitterKit/TwitterKit.h>

@interface FABListTimelineViewController : TWTRTimelineViewController
@end

// FABListTimelineViewController.m
#import "FABListTimelineViewController.h"
#import <TwitterKit/TwitterKit.h>
@implementation FABListTimelineViewController

- (void)viewDidLoad {
  [super viewDidLoad];

  TWTRAPIClient *APIClient = [[TWTRAPIClient alloc] init];
  self.dataSource = [[TWTRListTimelineDataSource alloc] initWithListSlug:@"twitter-syndication-team" listOwnerScreenName:@"benward" APIClient:APIClient];
}

@end
// Swift

// ListTimelineViewController.swift
import UIKit
import TwitterKit

class ListTimelineViewController: TWTRTimelineViewController {
    override func viewDidLoad() {
        super.viewDidLoad()

        let client = TWTRAPIClient()
        self.dataSource = TWTRListTimelineDataSource(listSlug: "twitter-syndication-team", listOwnerScreenName: "benward", APIClient: client)
}
List Timeline

Collection Timeline

The Twitter collections documentation describes collection timelines and shows how they can be created and managed. One approach is through TweetDeck as described in this post.

After you’ve created a collection, view it on twitter.com, and get the id from the address bar. The example Twitter Music Superstars collection has id 393773266801659904. Create a TWTRCollectionTimelineDataSource and provide it to a TWTRTimelineViewController.

Here’s an example of setting up a Collection timeline with TWTRTimelineViewController and TWTRCollectionTimelineDataSource:

// Objective-C

// FABCollectionTimelineViewController.h
#import <UIKit/UIKit.h>
#import <TwitterKit/TwitterKit.h>

@interface FABCollectionTimelineViewController : TWTRTimelineViewController
@end

// FABCollectionTimelineViewController.m
#import "FABCollectionTimelineViewController.h"
#import <TwitterKit/TwitterKit.h>
@implementation FABCollectionTimelineViewController

- (void)viewDidLoad {
  [super viewDidLoad];

  TWTRAPIClient *client = [[TWTRAPIClient alloc] init];
  self.dataSource = [[TWTRCollectionTimelineDataSource alloc] initWithCollectionID:@"393773266801659904" APIClient:client];
}

@end
// Swift

// CollectionTimelineViewController.swift
import UIKit
import TwitterKit

class CollectionTimelineViewController: TWTRTimelineViewController {
  override func viewDidLoad() {
    super.viewDidLoad()

    let client = TWTRAPIClient()
    self.dataSource = TWTRCollectionTimelineDataSource(collectionID: "393773266801659904", APIClient: client)
  }
}
Collection Timeline

Filter Timeline

Twitter Kit provides functionality to filter the Tweets displayed in your app, according to rules you provide. You can use this functionality to prevent showing Tweets with profane words, hide Tweets that link to blacklisted URLs, or block specific user’s Tweets from appearing in your app. The rules can be managed in a standard JSON configuration file and used on any timeline in Twitter Kit for Android and iOS.

The TWTRTimelineDataSource supports the timelineFilter property to filter timeline contents. The TWTRTimelineFilter object supports filtering of Tweets by hashtags, URLs, handles, and keywords.

class SearchFilteredTimelineViewController: TWTRTimelineViewController {

  convenience init() {
      // define a search timeline
      let client = TWTRAPIClient()
      let dataSource = TWTRSearchTimelineDataSource(searchQuery: "twitter", apiClient: client)

      // filter the search timeline
      let filter = TWTRTimelineFilter()
      filter.keywords = [ "book", "phone" ]
      filter.hashtags = [ "#twitter", "#followme" ]
      filter.urls = [ "twitter.com", "fabric.io" ]
      filter.handles = [ "ericfrohnhoefer", "benward", "vam_si", "katejaiheelee", "esacrosa" ]
      dataSource.timelineFilter = filter

      self.init(dataSource: dataSource)
  }
}

Using the TWTRTimelineFilter, you can specify four different filters with the available properties.

Filter Value Description
keywords Removes Tweets containing specified keywords in a Tweet’s text. Uses localized case-insensitive matching.
hashtags Removes Tweets containing specified hashtags. Uses localized case-insensitive matching.
handles Removes Tweets from specified users or replies to specified users. Uses case-insensitive matching.
urls Removes Tweets containing URLs from specified domain. Supports internationalized domain names.

You can easily load your filter settings using a JSON configuration file, like so:

{
  "keywords": [
    "dummy"
  ],
  "hashtags": [
    "cookies"
  ],
  "handles": [
    "benward",
    "vam_si",
    "ericfrohnhoefer",
    "katejaiheelee",
    "esacrosa"
  ],
  "urls": [
    "example.com"
  ]
}
class SearchFilteredTimelineViewController: TWTRTimelineViewController {
  convenience init() {
    let client = TWTRAPIClient()
    let dataSource = TWTRSearchTimelineDataSource(searchQuery: "twitter", apiClient: client)

    // filter the search timeline by loading the json file from bundle
    if let jsonData = NSData(contentsOfFile: Bundle.main.path(forResource: "filters", ofType: "json")!) {
      do {
          // parse dictionary values from the json file contents
          if let dictionary = try JSONSerialization.jsonObject(with: jsonData as Data, options: .allowFragments) as? [String : Any] {
              // simply supply a dictionary of values to the filters initializer
              if let filter = TWTRTimelineFilter(jsonDictionary: dictionary) {
                  dataSource.timelineFilter = filter
              }
          }
      } catch {
          // Could not load JSON file
      }
    }

    self.init(dataSource: dataSource)
  }
}

The above example loads the configuration from a JSON file in the bundle. However, you can store the configuration file locally or pull it from a remote server to deliver over-the-air updates to your filter configuration. You can use the same configuration file for Twitter Kit on both Android and iOS.