Twitter Plugin for Corona SDK

I created the Twitter plugin for Corona SDK to give Corona developers an easy way to access the full range of Twitter’s REST APIs from inside their apps, making it simple to get data from or post information to a Twitter user’s account with as little as a single line of code. The plugin automatically handles oAuth authentication, and persistently saves a logged-in user’s token data, so they’ll only need to log in and authorize your app once, even across multiple sessions, until they are manually logged out or revoke your app’s access to their Twitter account. The plugin also comes with a set of “convenience functions” that return Lua tables and/or Corona display objects, for easier access to common-use applications without the need for developers to wade through the raw JSON data that Twitter’s REST APIs return.

This page contains the documentation for the plugin, as well as a sample project you can download and run to see the plugin in action for yourself. Please check back, as I will continue to update this page whenever bug fixes or new features are added.

Table of Contents

• Change Log
• Adding the Plugin to Your App
• Twitter App Registration
• Initializing the Plugin
• Core Plugin Functions
  • twitter.login()
  • twitter.logout()
  • twitter.request()
• Convenience Functions
  • twitter.tweet()
  • twitter.search()
  • twitter.follow()
  • twitter.getUser()
  • twitter.getFollowers()
  • twitter.getFriends()
  • twitter.getProfileImage()
• Error Handling
• Other Plugin Features
• “Gotchas”
• Demo Project

Change Log

• 7/15/2015 :
  1. Initial public release.
• 7/19/2015 :
  1. Modified twitter.login() to accept a second “onFail” argument, allowing developers to respond to cancelled or failed login attempts.
• 7/20/2015 :
  1. Modified twitter.login() to accept a third “windowsSimulatorToken” string argument, to allow the plugin to run in the Corona Simulator for Windows, working around the Windows simulator’s lack of support for native webViews.
• 8/14/2015 :
  1. Deprecated old “windowsSimulatorToken” argument to twitter.login(), which required you to modify your code and relaunch the Simulator to use the plugin in the Windows Simulator. Instead, calling twitter.login() in the Windows simulator now presents you with a native text field where you can simply paste in your oAuth token string. NOTE: You now must be using SDK build # 2015.2695 or later to use the plugin in the Windows Simulator. This is because native text fields were only introduced for the Windows simulator starting with daily build 2015.2695. Calling twitter.login() in earlier SDK builds will pop up a system alert asking you to update your SDK.
• 8/24/2015 :
  1. Added improved support for image uploads, including automatic conversion of image files to multipart/form-data. Specifically, the “statuses/update_with_media” endpoint now works if you add a key/value pair to your parameters table with the key “media” and a value that uses Corona’s system.pathForFile() API to return an absolute path to the image file you want to upload. Also modified the twitter.tweet() convenience function to accept an optional string argument representing an image that gets attached to the tweet. Updated sample project to upload an image when trying out the twitter.tweet() function.
• 10/27/2015 :
  1. Fixed a bug that was preventing twitter.tweet() from posting tweets with an attached image in the Windows Simulator and on Android devices. For more details on this bug and details on the fix, please see this Corona Labs forum post.
• 2/17/2016 :
  1. Fixed a bug that caused the login webview to be placed incorrectly on the screen if default anchorX and anchorY values are adjusted globally using display.setDefault().
  2. Added support for error handling in callback functions. Callback functions previously only supported a single argument. They now accept up to 3 arguments: the response from Twitter (same as before), an “isError” boolean and a Corona networkRequest event table (only if there was an error). See the new Error Handling section below for details. Note that this change is backwards-compatible with previous versions of the plugin – you don’t need to change your code if you are happy with the way it was.
• 3/23/2016 :
  1. Fixed issue where a (non-used) global variable “tempTable” was set to nil.
  2. Fixed issue with twitter.getFollowers() that could result in a Runtime error if Twitter’s returned JSON data contained no ‘users’ subtable.
• 1/16/2017 :
  1. Added support for Windows Simulator webviews – this means no more windowsSimulatorToken workaround required! NOTE: You must be using Corona Simulator daily build 2016.3011 or later to take advantage of this.
  2. The twitter login webview will now clear its cache (on-device) every time it loads. Previously, it was stubbornly retaining the last logged-in user’s credentials.
  3. Added the new optional logoutSimulator argument to twitter.logout.
• 4/14/2017 :
  1. Fixed a bug that could potentially cause the login webview to be placed off-center (and hence only cover part of the screen) depending on certain values in config.lua. The webview will now be centered and fullscreen in all circumstances.
• 12/4/2017 :
  1. Fixed issue with sample project where main.lua was missing line breaks.
  2. Update sample project to newer style of iOS icon & launchscreen (removing old icon & “Default” PNGs).

Adding the Plugin to Your App

Before you can require the plugin for use in your app, you’ll need to do two things:

1. Activate the plugin for your Corona developer account at store.coronalabs.com
2. Add an entry into a plugins table of your build.settings. The following is an example of a minimal build.settings file with the required entry for the Twitter plugin:

settings =
{
    plugins =
    {
        -- @schroederapps' Twitter plugin:
        ["plugin.twitter"] = {
            publisherId = "com.jasonschroeder",
        },
    },      
}

After you’ve taken the above steps, you can require the plugin in your app with just one line of code:

local twitter = require("plugin.twitter")

Twitter App Registration

The Twitter plugin must be initialized with an “API Key” and “API Secret,” which are string values that identify a Twitter app you set up at apps.twitter.com (it’s free). Here’s a quick primer on setting up a new Twitter app and obtaining your app’s API Key and API Secret:

1. Go to apps.twitter.com and click the “Create New App” button.
2. Fill in all the fields with your app’s name, description, website and a callback URL. Note that while it doesn’t matter what your callback URL is, you MUST include one for the plugin to work correctly, even though Twitter does not consider it a required field.
3. On your new app’s developer page, click the “Keys and Access Tokens” button. The API Key and API Secret will be shown, for easy copying and pasting into your Corona app. It’ll look something like this:

Initializing the Plugin

Now that you have your Twitter app’s API Key and API Secret, call twitter.init() in your Corona app, preferably just after requiring the plugin. It should look something like this:

local twitter = require("plugin.twitter")

twitter.init("API_KEY", "API_SECRET")
-- replace API_KEY & API_SECRET with your Twitter app's API Key & API Secret

Core Plugin Functions

The three functions detailed below are all you need to access the full range of Twitter’s REST API. Unlike the “convenience functions,” these functions do not process any of the raw JSON data Twitter’s APIs return for you. These functions – and in particular, twitter.request() – take more effort on your part to integrate into your Lua code, but they also offer you the greatest flexibility and control over the data Twitter gives you access to.

twitter.login( [onSuccess], [onFail], [windowsSimulatorToken] )

Before you can make any Twitter API requests, your user must sign in and authorize your app to access their Twitter account. You do this by calling twitter.login(). You only have to do this once – a logged in user will remain logged in until you manually log them out or they revoke your app’s access to their Twitter account, even if they quit your app. While the plugin will automatically prompt your user to log in if you make an API request before doing so, by using twitter.login(), you have the option of logging them in without making a subsequent API request. twitter.login() accepts two optional arguments:

• onSuccess : a function that is run when a user successfully logs in
• onFail : a function that is run when a login attempt fails (either because the user entered an invalid user/password combination, or because the user cancelled the attempt on purpose)
• (DEPRECATED ON 8/14/2015) windowsSimulatorToken : this is a string value that is required if you want to use the plugin in the Windows simulator. This argument is not required and will be ignored on all device builds and in the OS X Simulator, but it is the only way to work around the Windows simulator’s lack of support for native webViews. When you call twitter.login() in the Windows simulator, the Twitter authorization webpage will open in a separate browser window. Click “authorize app” and you will be redirected to a webpage that displays a valid windowsSimulatorToken string in red. Copy and paste that string as an argument to twitter.login() and relaunch the Simulator. This time, when your app calls twitter.login() the plugin will log in successfully, and keep you logged in even if you relaunch the Simulator, so long as you don’t call twitter.logout(). Note that a windowsSimulatorToken is single-use, so calling twitter.logout() will require you to obtain another valid windowsSimulatorToken string. The plugin will automatically detect if you have an expired windowsSimulatorToken and prompt you to obtain a new one if necessary.

Sample Code:

local function onSuccess()
	print("Twitter user " .. twitter.user.screenName .. " successfully logged in!")
end

local function onFail()
	print("Twitter login attempt failed or was cancelled by user.")
end

twitter.login(onSuccess, onFail)

twitter.logout( [callbackFunction], [logoutSimulator] )

twitter.logout() logs out the currently logged-in Twitter user. twitter.logout() accepts two optional arguments:

1. callbackFunction: a callback function that will be run on a successful logout
2. logoutSimulator: a boolean that when set to “true” will prompt the user to log out of Twitter in a webview when you call twitter.logout() in the Corona Simulator. This is only applicable in the simulator, where Corona webviews stubbornly retain the last logged-in user. If you need to be able to switch users in your app in the simulator, set this value to “true” and confirm that you want to log out in the resulting simulator.

Sample Code:

local function callback()
     print("Logout successful.")
end

twitter.logout(callback, true)

twitter.request( requestTable )

twitter.request() is the backbone of the Twitter plugin. It allows you to easily make an API call against any of Twitter’s public REST API endpoints, and pass the resulting JSON data into a callback function. All the “convenience functions” built into the plugin like twitter.tweet() and twitter.search() use twitter.request() behind the scenes, and then they convert the returned JSON data to a more manageable Lua table. You can easily recreate those functions, then tweak them to your liking, by using twitter.request().

twitter.request() requires a single Lua table as an argument, containing the following key/value pairs:

• endpoint: a string representing the API endpoint you want to use (e.g. “statuses/retweets_of_me” or “direct_messages”). A full list of available endpoints can be found at http://dev.twitter.com/rest/public.
• method: a string representing the HTTP method employed by the endpoint you are using. As of July 2015, the only valid methods for Twitter’s API are “GET” and “POST” (and that’s unlikely to change).
• parameters: a Lua table containing key/value pairs for the required and/or optional parameters for the endpoint you are using. Check Twitter’s API docs for details on each API’s accepted parameters.
• callback: a Lua callback function that accepts a single argument, representing the JSON data string returned by Twitter.

As an example, below is an simple twitter.request() call that would search Twitter for the phrase “@schroederapps” and pass the resulting JSON string into a function called “myCallback” that prints that string to the terminal. Note that there are optional parameters for the “search/tweets” API that are not being used in this example, but they could be by adding key/value pairs to the “parameters” table:

Sample Code:

local function myCallback(response)
	print("Twitter JSON response: " .. response)
end

twitter.request({
	endpoint = "search/tweets",
	method = "GET",
	parameters = {
		q = "@schroederapps",
	},
	callback = myCallback,
})

Convenience Functions

The core plugin functions are all you need to access the full range of Twitter’s public APIs, but properly handling the returned data requires you to decode the JSON string and pull out the relevant data for your needs, which can sometimes be complicated. To make this easier, I have created a handful of “convenience functions” that offer a simpler way to make certain API requests, automatically interpret the raw JSON data returned by Twitter, and pass on either a Lua table or a Corona display object into a callback function.

twitter.tweet( status, [imageFile], [callbackFunction] )

twitter.tweet() posts a status update to the logged-in user’s timeline. It accepts up to three arguments: a required string representing the text of the status update, an optional string representing an image file to upload and attach to the tweet, and an optional callback function that accepts a single Lua table as an argument.

The imageFile argument is designed to be very accommodating: you can use Corona’s system.pathForFile() API to pass in an absolute path to the file, but you can also just pass in a file name like you would when calling display.newImage() and the plugin will automatically convert that file name into an absolute path. It will also look in the system.DocumentsDirectory and system.TemporaryDirectory (in that order) if it cannot first find the file in the system.ResourceDirectory. Here are three examples of valid imageFile arguments that would result in a successful upload (assuming that these image files existed in the app sandbox):

• system.pathForFile(“display-save-screenshot.jpg”, system.DocumentsDirectory)
• “images/twitterImage.png”
• “Default.png”

The Lua table that is passed into the callback function has two key/value pairs:

• text: the text of the status update
• id: the tweet’s ID string, which can be used to reference the tweet later on (should you want to delete it, for example).

Sample Code:

local function tweetCallback(response)
	print("TWEET TEXT: " .. response.text)
	print("TWEET ID: " .. response.id)
end

twitter.tweet("I love the Twitter plugin for #CoronaSDK!", "images/twitterImage.png", tweetCallback)

twitter.search( searchTerm, callbackFunction, [parameters] )

twitter.search() searches Twitter for tweets that contain your specified search term. It accepts up to three arguments: a required string representing your search term, a callback function that accepts a single Lua table as an argument, and an optional table that contains additional search parameters.

The optional parameters table can contain any of the following key/value pairs:

• resultType: a string indicating which types of results you want Twitter to return. Valid options are “mixed”, “recent”, or “popular”. Defaults to “mixed”.
• count: A number representing the number of tweets to return, up to a maximum of 100. Defaults to 15.
• retweets: A boolean indicating whether or not to include retweets in search results. Defaults to true.

The Lua table that is passed into the callback function contains a numeric array of tables, one for each returned tweet. Each of these “tweet tables” contains four key/value pairs:

• text: the text of the tweet
• id: the tweet’s ID.
• timeStamp: a string indicating when the tweet was posted.
• screenName: the screen name of the Twitter user who composed the tweet.

The Lua table that is passed into the callback function also contains two additional key/value pairs that are useful for searches with more results than can be collected at once (Twitter limits search results to 100 per API call):

• isMore: a boolean indicating whether or not there are still more tweets in your search results
• getMore: a function that will automatically get the next set of search results, if any more tweets exist.

Sample Code:

local function searchCallback(results)
	for i = 1, #results do
		local tweet = results[i]
		print("TEXT: " .. tweet.text)
		print("TWEET ID: " .. tweet.id)
		print("TIME STAMP: " .. tweet. timeStamp)
		print("SCREEN NAME: " .. tweet.screenName)
	end
	
	if results.isMore then
		results.getMore()
	else
		print("END OF SEARCH RESULTS")
	end
end

twitter.search("#CoronaSDK", searchCallback, {resultType = "recent", count = 100, retweets = false})

twitter.follow( screenName, [callbackFunction] )

twitter.follow() makes the logged-in user a follower of any Twitter account you specify. It accepts up to two arguments: a required string representing the Twitter account to follow and an optional callback function that accepts a single Lua table as an argument.

The Lua table that is passed into the callback function contains ten key/value pairs of data from the followed user’s Twitter profile:

• screenName: the user’s screen name – this will always be the same as the screen name you specified when calling twitter.follow()
• name: the user’s display name
• userID: the user’s numeric user ID
• location: the user’s location
• followersCount: the number of followers the user has
• friendsCount: then number of accounts the user follows
• tweetsCount: the number of tweets the user has posted
• favoritesCount: the number of tweets the user has “favorited”
• verified: a boolean indicating if the user has a “verified” profile (for celebrities, etc.)
• following: a boolean indicating whether or not the logged-in user is following this account – this will always be true

Sample Code:

local function followCallback(results)
	print ("SCREEN NAME: " .. results.screenName)
	print ("DISPLAY NAME: " .. results.name)
	print ("USER ID: " .. results.userID)
	print ("LOCATION: " .. results.location)
	print ("# FOLLOWERS: " .. results.followersCount)
	print ("# FOLLOWING: " .. results.friendsCount)
	print ("# TWEETS: " .. results.tweetsCount)
	print ("# FAVORITES: " .. results.favoritesCount)
	print ("VERIFIED: " .. tostring(results.verified))
	print ("I AM FOLLOWING: " .. tostring(results.following))
end

twitter.follow("@schroederapps", followCallback)

twitter.getUser( [screenName], callbackFunction )

twitter.getUser() looks up a Twitter user and returns an array of data from his or her Twitter profile. It accepts up to two arguments: an optional string (“screenName”) representing a Twitter user name to look up (if screenName is nil, the logged-in user will be looked up) and a required callback function that accepts a single Lua table as an argument.

The Lua table that is passed into the callback function contains ten key/value pairs of data from the followed user’s Twitter profile:

• screenName: the looked-up user’s screen name
• name: the looked-up user’s display name
• userID: the looked-up user’s numeric user ID
• location: the looked-up user’s location
• followersCount: the number of followers the looked-up user has
• friendsCount: then number of accounts the looked-up user follows
• tweetsCount: the number of tweets the looked-up user has posted
• favoritesCount: the number of tweets the looked-up user has “favorited”
• verified: a boolean indicating if the looked-up user has a “verified” profile (for celebrities, etc.)
• following: a boolean indicating whether or not the logged-in user is following the looked-up user

Sample Code:

local function getUserCallback(results)
	print ("SCREEN NAME: " .. results.screenName)
	print ("DISPLAY NAME: " .. results.name)
	print ("USER ID: " .. results.userID)
	print ("LOCATION: " .. results.location)
	print ("# FOLLOWERS: " .. results.followersCount)
	print ("# FOLLOWING: " .. results.friendsCount)
	print ("# TWEETS: " .. results.tweetsCount)
	print ("# FAVORITES: " .. results.favoritesCount)
	print ("VERIFIED: " .. tostring(results.verified))
	print ("I AM FOLLOWING: " .. tostring(results.following))
end

twitter.getUser("@coronalabs", getUserCallback)

twitter.getFollowers( [screenName], callbackFunction )

twitter.getFollowers() returns an array of data on a Twitter user’s followers. It accepts up to two arguments: an optional string (“screenName”) representing a Twitter user name to look up (if screenName is nil, it will default to the logged-in user’s screen name) and a required callback function that accepts a single Lua table as an argument.

The Lua table that is passed into the callback function contains a numeric array of tables, one for each returned follower. Each of these “follower tables” contains four key/value pairs:

• screenName: the follower’s screen name
• name: the follower’s display name
• userID: the follower’s numeric user ID
• isFriend: a boolean indicating whether or not the follower is a “friend” of the looked-up user (i.e. does this person follow the follower back?)

The Lua table that is passed into the callback function also contains two additional key/value pairs that are useful for searches with more results than can be collected at once (Twitter limits follower lookups to 200 per API call):

• isMore: a boolean indicating whether or not there are still more followers
• getMore: a function that will automatically get the next set of up to 200 followers, if there are any

Sample Code:

local function followerCallback(results)
	for i = 1, #results do
		local follower = results[i]
		print("FOLLOWER # " .. i)
		print("SCREEN NAME: " .. follower.screenName)
		print("DISPLAY NAME: " .. follower.name)
		print("USER ID: " .. follower.userID)
		print("IS A FRIEND: " .. tostring(follower.isFriend))
		print("*****************")
	end
	
	if results.isMore then
		results.getMore()
	else
		print("NO MORE FOLLOWERS")
	end
end
 
twitter.getFollowers("coronageek", followerCallback)

twitter.getFriends( [screenName], callbackFunction )

twitter.getFriends() returns an array of data on a Twitter user’s friends (the Twitter accounts that he or she follows). It accepts up to two arguments: an optional string (“screenName”) representing a Twitter user name to look up (if screenName is nil, it will default to the logged-in user’s screen name) and a required callback function that accepts a single Lua table as an argument.

The Lua table that is passed into the callback function contains a numeric array of tables, one for each returned friend. Each of these “friend tables” contains three key/value pairs:

• screenName: the friend’s screen name
• name: the friend’s display name
• userID: the friend’s numeric user ID

The Lua table that is passed into the callback function also contains two additional key/value pairs that are useful for searches with more results than can be collected at once (Twitter limits friend lookups to 200 per API call):

• isMore: a boolean indicating whether or not there are still more friends
• getMore: a function that will automatically get the next set of up to 200 friends, if there are any

Sample Code:

local function friendCallback(results)
	for i = 1, #results do
		local friend = results[i]
		print("FRIEND # " .. i)
		print("SCREEN NAME: " .. friend.screenName)
		print("DISPLAY NAME: " .. friend.name)
		print("USER ID: " .. friend.userID)
		print("*****************")
	end
	
	if results.isMore then
		results.getMore()
	else
		print("NO MORE FRIENDS")
	end
end
 
twitter.getFriends(friendCallback)

twitter.getProfileImage( [screenName], callbackFunction, [size] )

twitter.getProfileImage() is a modified version of Corona’s built-in display.loadRemoteImage() API that creates a display object consisting of a Twitter user’s profile image. It accepts up to three arguments: an optional string (“screenName”) representing a Twitter user (if screenName is nil, the logged-in user will be looked up), a required callback function that accepts a single Lua table as an argument, and an optional string (“size”) indicating what size image you want to load. The “size” argument has only four acceptable values:

• “original” : this returns the original image that the user uploaded to their profile, which is the highest-quality version available, but may also be larger than you need. (This is the default value.)
• “normal” : this returns an image sized 48×48>
• “bigger” : this returns an image sized 73×73>
• “mini” : this returns an image sized 24×24>

The Lua table that is passed into the callback function is identical to the “event” table that gets passed into Corona’s built-in display.loadRemoteImage() API. The table has a “target” parameter (“event.target”) that points to the returned display object (so you can assign it to a variable, insert it into a display group, etc.)

Sample Code:

local function imageCallback(event)
	local image = event.target
	
	sceneGroup:insert(image)
	image.x, image.y = display.contentCenterX, display.contentCenterY
end

twitter.getProfileImage("chiralgame", imageCallback, "original")

Error Handling

It is possible to gracefully handle errors in your callback functions in the event that the plugin is unable to successfully connect to Twitter to make a request, or that the request returned an error. Callback functions for twitter.request and all convenience functions can accept up to three arguments:

• results: the returned data from Twitter (this can be either a JSON string or a Lua table depending on the function being used).
• isError: a boolean value that is true in the event of an error. Will be nil if there is no error.
• event: a Corona networkRequest event table containing full details on the unsuccessful request. Will be nil if there is no error.

By checking to see if isError is true, you can manage an error in whatever way you see fit. Here is a code snippet showing one way to do that in the event of an error:

local function myCallback(response, isError, event)
    if isError then
        print("ERROR! Here's some details:")
        print("Status code: " .. tostring(event.status))
        print(event.response)
    else
        print("Success!")
        print("Twitter JSON response: " .. response)
    end
end
 
twitter.request({
	endpoint = "search/tweets",
	method = "GET",
	parameters = {
		q = "@schroederapps",
	},
	callback = myCallback,
})

Other Plugin Features

• twitter.showAlerts is a boolean value that, when set to true, will show a native alert dialog any time the plugin encounters an error. It can be useful for testing, but you’d probably want to set it to false when building for distribution. It defaults to false (but is set to true in the demo project).
• twitter.user is a table containing some basic information on the currently logged-in user, including:
  • twitter.user.screenName : the screen name for the currently logged-in user
  • twitter.user.userID : the numeric user ID for the currently logged-in user

“Gotchas”

The only “gotcha” with this plugin is that it requires an extra step to run in the Windows Simulator. This is because the only way to log in a user and seamlessly obtain their authentication token is through the use of a native.newWebView() object and a URL listener, and that Corona API isn’t supported in the Windows simulator. As a workaround, calling twitter.login() in the Windows simulator will open up a separate browser window with a valid oAuth token string you must paste into a native text field that pops up in the simulator. Entering in that token string allows the login process to complete in the Windows simulator. Consequently, because native web views were only introduced to the Windows simulator in Corona SDK daily build # 2015.2695, you must be using that build or later to use the plugin in the Windows simulator.

Note that if you build for device, or run it in the OS X simulator, the plugin will work seamlessly, with no extra steps required. If and when the Windows simulator gets support for the native.newWebView() API, I will update the plugin to remove this extra step.

Demo Project

I’ve created a free demonstration project that you can load in the simulator or build for device to see the Twitter plugin in action. The project is fully self-contained, so all you need to do is download it and open it in the simulator. However, you will need to register a Twitter app and add your app’s API Key and API Secret to the twitter.init() function call on line 15 of the project’s main.lua for it to work properly.

Here is a video of the app running on an iPad:

TP:34472E16