Prerequisite knowledge
 
This article requires that the reader have an understanding of HTML, CSS, and PHP. Sample files can be edited in any text editor. In addition, using the information in this article requires a Twitter account and access to a functional, public facing web server with PHP 5 or higher.
 
User level: Intermediate
 
Required Adobe products
 
  • Adobe Creative Cloud, DPS Pro or DPS Enterprise account to publish folios
  • Adobe InDesign CS5 or higher
Additional required other products
 
By downloading software from the Adobe Web site you agree to the terms of our license agreement. Please read it before downloading.
 
Note: If you have questions about this article, use the comments feature at the bottom of the article. Please don’t contact technical support with questions about Adobe Developer Connection articles.
 

 
Introduction

Recently, Twitter deprecated its 1.0 API in favor of their new 1.1 API. As a result, Twitter web widgets no longer display in DPS folios. This affects folios with embedded widgets and those that use widgets placed on web sites and displayed in Web Content Overlays. In this article, we will explore methods to restore Twitter functionality to DPS folios. (If you have the DPS Examples app installed on your iPad, and you're reading this article on your iOS device, then tap here to see an example of a working Twitter feed in the DPS Examples app.)
 

 
API Changes Explained

Twitter has a service called Twitter apps that allows customers to present Twitter-hosted content in their own contexts, such as on their company web site. The issue is that Twitter apps now require external authentication using PHP code, and DPS apps can’t run PHP in a folio. In addition, Twitter enforces a limit on the number of times a Twitter App can access its servers. Your app can make no more than 180 calls per 15 minutes, so even if your app could access the Twitter servers and you had a popular app, you would very quickly go over that 180 per 15 minute limit and your feed would stop working until the next 15 minute period. Consider a College Sports game day app that includes live feeds in the folio so that fans can watch that feed as the game evolves. Using the old method, this app would rapidly overwhelm the Twitter API call limit and would result in a poor user experience.
 
One solution is to create an external feed aggregator that polls Twitter on a schedule and then reflects those results to your DPS folio. Your Web Overlay would poll the feed aggregator instead of directly querying Twitter, which allows you to both authenticate and manage the number of server calls your folio makes to Twitter in total. We will explore that solution in the remainder of this article.
 

 
Create Your Twitter App

The first step is to create a Twitter app. You can use your company’s Twitter account or your personal Twitter account to create the app.
 
Navigate to https://dev.twitter.com/apps/ and login with your Twitter credentials. Click Create a new application to begin.
 
Create a new application
Figure 1. Create a new application
 
Fill in Application Details.
 
  • Name: You can call your app anything you want, but don’t use the word “Twitter” in the name. Consider using the name of your DPS app.
  • Description: Provide a description of your app, which is shown in user-facing authorization screens. This field is between 10 and 200 characters. Consider using your iTunes App description here.
  • Website: This is your app’s publicly available URL. For a DPS-based feed, consider putting the iTunes URL to your app here.
  • Callback URL: You can leave this blank.
  • Agree to the Rules of the Road
  • Enter the Captcha, if you can make sense of it.

 

Fill in the details
Figure 2. Fill in the details
 
  • Once complete you will see a page that lists all of the particulars you will need in the rest of this article, including your consumer key and consumer secret.
Create the token and key
Figure 3. Create the token and key
 
  • Click Create my access token to create your access token and access key.
Your Twitter App credentials
Figure 4. Your Twitter App credentials
 
  • Make note of your Consumer key, Consumer secret, Access token, and Access token secret, which you will need later.

 
Set Up Your feed

Now, we need to use the Twitter App keys so that our feed can authenticate itself. In order to do this, we need to use a tool to fetch the feed that leverages an oAuth client compatible with Twitter. Lastly, we need to host the tool and pages to leverage the tool on a web site in a publicly available location. Download the file twitter_feed_example_code.zip at the top of this article and extract the ZIP archive to a working directory. You will need to have access to an FTP client to push these files to a web site, too. We will reference files from that directory going forward. We will go through the configuration first, and then we will explain how it all works.
 
There are existing oAuth clients available under GNU and other licensing. For our example, we have used a project by Abraham Williams called twitteroauth. If you would like the latest version, navigate to https://github.com/abraham/twitteroauth and click on the Download ZIP button to download the project files. We have included the latest version (as of this writing) in the sample files. Consider opening an account on GitHub, as it provides a robust platform for code collaboration. Also, signed in users have access to additional tools and services, and it’s free.
 
Abraham Williams’ twitteroauth on GitHub
Figure 5. Abraham Williams’ twitteroauth on GitHub
 
 
Once you download the bundle, move it into your working directory (where you unpacked the sample files) and unpack the ZIP. We will use it as is, so you won’t need to make changes to it. You can then replace the existing library that’s in the sample folder. Now that we have the oAuth client, we need to make the tool that fetches and caches your tweets.
 
In your widget, you might want to show tweets related to a specific handle, show tweets related to a hash tag or text search, or fetch tweets related to a combination of the two. In our example, we are providing a feed based on a specific Twitter handle. Of course, you can modify the code to suit your specific requirements. We have included a file called settings.php in the example files. This file allows get-tweets.php to connect to your Twitter app. Open the file called settings.php in your favorite text editor so that you can connect it to your app and tell it what to display.
 
First, replace the 4 keys with the keys you noted from your Twitter app. This will allow get-tweets.php to talk to Twitter using the oAuth client we fetched earlier. Next, enter the Twitter user name whose tweets you would like to display.
 
Modifying settings.php
Figure 6. Modifying settings.php
 
 
Once you have made your changes, save and close the file.
 
We need to make two additional changes in order for our feed to work properly. The feed will leverage a JavaScript file called from the CSS that will use get-tweets.php to get a json encoded file that represents the tweets. Did you catch all that? This file is called twitterfeed.js and it resides in the /js folder. We need to hard code the path to where you will deploy get-tweets.php so that the JavaScript can locate it and use it as a json provider for your feed.
 
This feed comes to us by way of Tom Elliott, who is a developer and who posts some pretty amazing solutions at www.webdevdoor.com. Tom provides a Custom jQuery Twitter Feed that works with the current (V1.1) Twitter API, and we use it here with slight modification. If you want to see the original code, then please visit Tom’s site. We have included the modified code in our example.
 
Open the file at /js/twitterfeed.js and replace the path in the getJSON request with the path to where you will deploy get-tweets.php. This path needs to be publicly accessible so that your DPS folios or storefront can be sure to find it when they need it.
 
In addition, we need to make a cosmetic change. The feed will be presented as a list of Tweets, with your name at the top and a link to your feed on twitter.com. You need to change twitterprofile to match the profile you entered back in settings.php, and set screenname to the “regular” name of the person or group whose tweets you’re displaying. Once you make the changes, save and close the file.
 
Modifying twitterfeed.js
Figure 7. Modifying twitterfeed.js
 
 
Now, it’s time to upload the project to a publicly accessible folder, ideally on your web site. Remember that the path to the published content must match what you entered in twitterfeed.js. After you upload your project folder to your web site, be sure to check the permissions on tweets.txt, as it needs to be read and write by everyone. Set the UNIX permissions to 666 or use your FTP utility to set the permissions to read and write for owner, group and others.
 
Adjust permissions on tweets.txt
Figure 8. Adjust permissions on tweets.txt
 

 
So, how does it all work?

Now that you have your project posted to your web site, you are ready to test it out. Browse to tweets.html at your deployed location in your browser to test the feed.
 
The feed in a browser
Figure 9. The feed in a browser
 
 
As designed, the feed sits in a white box on a transparent background. You should probably tune up the CSS to make it more in line with your branding. If you get a constantly spinning ball rather than the feed, check the permissions on tweets.txt. It is critical that your app can write to that file. If it can’t, the feed won’t work.
 
Ensure Auto Play and Allow User Interaction in your Web Content overlay
Figure 10. Ensure Auto Play and Allow User Interaction in your Web Content overlay
 
 
In InDesign, make a box and set it to be a Web Content Overlay. Point it at your tweets.html file hosted on your web site, and then preview the overlay on your tablet with Content Viewer or desktop.
 
The feed on an tablet in an article
Figure 11. The feed on an tablet in an article
 
 
Now, when your customers access the feed from their folios, the feed automatically selects either a json encoded file called tweets.txt or refreshes the feed from Twitter. This allows you to restrict the number of server calls that get made to the Twitter APIs and your readers always get some Tweets. Look in the code comments at the top of get-tweets.php to see how we’re selecting either the cached file or the fresh Tweets. You can adjust the buffer time in settings.php by changing $time_offset.
 

 
Where to go from here

You can (and probably should) modify the CSS of the feed to make it match your brand, as stated before. You can add more posts by adjusting the displaylimit in twitterfeed.js. You might also include an auto refresh on the feed so that it will appear to feed. You can also get fancy with delaying the appearance of the feed elements. There is a great example of this in the Notre Dame Game Day app, which was designed by the geniuses at Joe Zeff Design, who also contributed to this article.
 
While this solution provides a stable Twitter feed for your DPS applications, it is possible that Twitter will once again change its API or its policies with respect to how the Twitter Apps may be used. Be sure to check with the Twitter apps page to see the latest information about both APIs and usage policies.
 
Comments are currently closed as we migrate to a new commenting system. In the interim, please provide any feedback using our feedback form. Thank you for your patience.