This is a simple version of the installation instructions for those who don’t own the Twitter API Engagement Programming book. The book contains much greater context for each of the scripts in this system, and also presents an overall engagement strategy for taking advantage of the scripts. It is available for sale from Amazon. If you already have the book, you should read chapters 3 and 4 for the installation process.

The source code available here for download is the same for everyone, whether you buy the book or not. Visit the download page for complete instructions.

The book’s source code is distributed with the MIT open source license. It is very liberal, and permits you to freely modify, copy, and distribute your versions of the code.

Installation instructions

The installation procedure for this code should take about 20 minutes to get the database and code set up, and then an hour or two of running some scripts that collect an initial set of data. The rest of the system runs with cron jobs that keep your data current. The code requires PHP and MySQL, both version 5 or higher. With the proper configuration, you can run this code on Linux, Windows, and Mac OS X computers.

1. Download the zip file with the source code for engagement programming to your computer. Unzip the files, which will contain the following directory structure:

/code
  /report
    /image

2. Create a directory on an internet accessible web server. On my server I used /var/www/engagement.

3. Upload the complete engagement programming source code into this server directory. The result in my case is /var/www/engagement/code and its sub-directories of /report and /report/images.

4. The report system for this code ends up at /var/www/engagement/code/report. The reports are all done with HTML, so they must be run through a web browser. To use the report system you have to make the /report directory web accessible. There are several ways to do this. I chose to create a subdomain of 140dev.com called engagement-reports.140dev.com. First I created a DNS entry with this subdomain that pointed to the IP address of my server. Then I added an Apache config entry for this subdomain that pointed to the /report directory.

<VirtualHost *:80>
    DocumentRoot /var/www/engagement/code/report
    ServerName engagement-reports.140dev.com
</VirtualHost>

5. You should already have MySQL installed on your server. Use phpMyAdmin or whatever tool you prefer, and create a database called ‘engagement’ in MySQL.

6. Import the table schema from the file /code/engagement.sql into the engagement database. A simple tool for this is the import link in phpMyAdmin.

7. Edit the /code/config.php file in the source code and fill in the $db_user and $db_password variables to match the user and password for the engagement database.

8. Tweets and users that you will interact with using this code are based on 2 sets of accounts. Leader accounts are well known users in the subject area that interests you. It is best to start with 2 or 3 leader accounts, and then add more as you discover the top influencers. The other type of account is the engagement account, which is the one you want to build influence around and grow in followers. You will need the screen name and user id of the leader accounts and the engagement account.

9. Use the API Console on this site to display the user id for any matching screen name. This URL will get you started. http://140dev.com/twitter-api-console/?method=GET&url=1.1/users/show&screen_name=justinbieber&run=1

10. When you have the screen name and user id for a couple of leader accounts and one engagement account, they must be added to the engagement database. Insert new rows into the leaders table, and fill in the screen_name and user_id values for the leader accounts. Then insert a single row into the engagement_account table, and fill in the screen_name and user_id.

11. You also have to add the engagement account into the config.php file. Fill in the $engagement_user_id and $engagement_screen_name fields in this file.

12. All of your API requests will have to be done with OAuth tokens. The account you will be modifying is the engagement account. So log into http://dev.twitter.com with that account.

13. Create a new app with an access level of Read, Write, and Access Direct Messages. Create a set of OAuth tokens for this app. This code will use the app’s own tokens. This coding style is commonly called single-user OAuth programming.

14. Fill in the OAuth tokens in the config.php file. Now you are ready to start running the source code.

15. Log into the web server with telnet or SSH, and go to the code directory. Run the /code/test_install.php script:

cd /var/www/engagement/code/
php test_install.php

This script will collect the user account profile and most recent tweet for the engagement account. You can look at them directly in the database.

16. Now you can test the report system code by going to the URL with your browser that you configured for web access. This was done in steps 2 through 4. Make sure you followed those steps and created a path to the report code on a web accessible server. When you visit the site, you will see an “engagement account” link in the top of the sidebar menu. Clicking that link should display engagement account data.

17. The final set of installation steps is running the scripts that collect the starting data for the leader and engagement accounts. To avoid exceeding any rate limits, the safest approach is to run each of these scripts with 15 minute intervals. You only have to do this once. The rest of the scripts can be set up to run as automatic cron jobs.

Log into your web server and run this list of scripts with a 15 minute pause between each execution:

cd /var/www/engagement/code/
php collect_old_leader_timeline.php
    Run this script once for each leader account with a 15 minute pause between each execution.
php collect_old_leader_search.php
    Run this script once for each leader account with a 15 minute pause between each execution.
php collect_leader_account_profiles.php
php collect_old_engagement_timeline.php
php collect_old_engagement_search.php
php collect_old_dms_sent.php
php collect_old_dms_received.php

18. This install procedure gets your system primed with fresh data for engagement. To keep it up-to-date you need to run the rest of the scripts with these cron jobs. You should read each script before turning it on as a repeating cron job.