After a few years of releasing games and updates for those games with very little-to-no feedback on them, it was easy to be under the impression that nobody was playing my games. Though I didn’t do it for the fame, and certainly not for the fortune (seeing as thus far, all of my games have been released for free), it was still a little disheartening to feel that I was throwing all of this effort into a void and no one even saw the results of my efforts.

So one day this past April a random thought entered my mind: You know how some games display little status messages on events or deaths such as “JoeX got killed by a slime” or “SuzieQ didn’t bounce” or something similar? Wouldn’t it be fun if my games automatically tweeted little status messages like that?

Some of the benefits to doing this were as follows:

  1. I would have proof that people actually play my games.
  2. The tweets could include a hashtag of some sort which could help a bit with the publicity of my games.
  3. Interested players could follow the Twitter bot account or even game-specific hashtags to see what other players of my games were doing.

The next day I set about making this a reality. This blog post will detail the steps I took to implement a twitter bot in my games.

Clarification:

I feel I should clarify what exactly the Twitter bot does and what it doesn’t do, so that you know what you’re getting into before you follow all these steps.

What it isn’t:

  • This is not a way to get your players to tweet their high scores or other details to all of their friends/followers.
  • This is not a way to get access to your players’ Twitter contact list.
  • This is not a way to get access to any of your players’ Twitter account details.
  • This Twitter bot does not sign into your player’s Twitter accounts and make tweets on their behalf. It knows nothing about any Twitter account other than the account you’ll set up specifically for making the tweets. While I suppose you can use your own personal/business Twitter account to make the tweets, I personally chose to set up a separate account just for the Twitter bot.

What it is:

  • The Twitter bot is a Twitter account that tweets messages on its own account.
  • I repeat: The Twitter bot doesn’t know anything about your players’ Twitter accounts. It tweets on its own account only.
  • To see my Twitter bot in action, check out @DeozaanGames.

What You’ll Need:

  1. A Unity game. (This tutorial can probably be adapted to work with other programs/engines.)
  2. A webserver where you can host a couple PHP scripts:
    1. The TwitterAPIExchange.php file from this PHP Wrapper for Twitter. (Here’s my fork as a backup, with no changes.)
    2. The Tweeter.php file from my Tweeter gist (more details below).
  3. The Tweeter.cs file from my Tweeter gist somewhere in your Unity project.

Step 1: Creating/Configuring the Twitter Account

Create the Twitter account you will be using for the bot.

Use this link to create a new Twitter account. This step is pretty self-explanatory so I won’t go into any other details.

Create a Twitter “app” for making tweets.

  1. While signed into your Twitter bot’s account, go to apps.twitter.com.
  2. Click the “Create New App” button.
  3. Fill out the following details on the form:
Create Application
Click for full-size image.
  • Name:
    • This will be what is displayed when a tweet says something like “48 minutes ago from [Application Name Here]”
  • Description:
    • A description of the app. I use the same thing as Name here.
  • Website:
    • The website where the app/game can be downloaded.
  • Callback URL:
    • I use the same URL as the Website here.

Change the App’s Permissions

  1. From the newly created app page, click the Permissions tab.
  2. Change the Access to Read and Write.
  3. Click the “Update settings” button.

Generate API Keys

Click for full-size image.
Click for full-size image.
  1. Click the API Keys tab.
  2. Click the “Regenerate API keys” button. It will ask you if you’re sure you want to do this. Confirm that you do.
  3. Click the “Create my access token” button.
  4. If it doesn’t show your access token, wait a minute and refresh the page.
  5. This page should now show two keys and two tokens, both with the access level of “Read and write.”
  6. See the included image for an example (I’ve blurred out my keys/tokens since they should not be shared with others).

Step 2: Configuring the PHP Scripts on Your Web Host

Upload TwitterAPIExchange to your server.

  1. Upload the TwitterAPIExchange.php file anywhere on your web server, without modification.

Configure tweeter.php

Before uploading tweeter.php, you need to make a few changes to the file.

  1. Replace ACCESS_TOKEN with your Twitter App’s Access token on line 5.
  2. Replace ACCESS_TOKEN_SECRET with your Twitter App’s Access token secret on line 6.
  3. Replace CONSUMER_API_KEY with your Twitter App’s API key on line 7.
  4. Replace CONSUMER_API_SECRET with your Twitter App’s API secret on line 8.
  5. Replace URL_HERE with the URL of your game/program on line 12.
  6. Make sure the URL to your TwitterAPIExchange.php file is correct on line 15. It defaults to the same directory as the tweeter.php file.
  7. Save your changes to tweeter.php and upload it to your server.

Step 3: Tweeting from Unity

Import and Configure Tweeter.cs into Your Unity Project

  1. Import Tweeter.cs into your Unity project.
  2. Replace URL_PATH_HERE on line 9 with the location where tweeter.php is hosted on your server.
  3. Add Tweeter.cs to an object in your scene and set the Access Token Secret in the scene.
    • NOTE: It’s important that you do this in the scene inspector and not in the script file because anyone can easily decompile your code, exposing your secret to abuse. The scene gets bundled in builds in such a way that is more difficult to extract this information.
  4. Use Tweeter.Send(), passing in a string, to tweet the string.
    • NOTE: By default, tweeting from the editor is disabled to prevent tweets while testing. You can enable tweets in the editor from the inspector.
  5. If everything was configured correctly, your Twitter account should have made the tweet!
Configure Tweeter
Configure the Tweeter using the Inspector.

Caveats and Tips for using Tweeter

  • It’s up to you to enforce the 140 character limit. If you try to send a tweet that is longer than 140 characters, the tweet will fail (with some exceptions, such as using a long URL which Twitter will automatically shorten to 20 characters).
  • Take advantage of the string extensions I included in Tweeter.cs to help with tweets.
    • Use Truncate(myLength) to force a string to be at most myLength digits longs. This is useful for letting the player have some say in the tweet, for example, tweeting a username, but making sure it doesn’t get too long.
    • Use RemoveAtSymbol(myString) to make sure a myString does NOT contain an @ symbol at the beginning.
    • Use PrefixPeriod(myString) to automatically add a period at the beginning of myString if it starts with an @ symbol. This is useful for making sure a tweet that starts with a Twitter username is visible to everyone who follows your bot by default, instead of just being visible to the user the tweet was sent to.
    • Use GetFirstName(myString) to grab the first name out of a string that contains spaces. Useful when getting a name from a service like Google Play Games which returns both the first and last name.
  • It’s a good idea (in my opinion) to make a separate Twitter app for each game. They all post using the same Twitter account, but this way each game has its own dedicated Twitter app which gives links and info to its respective game.

The Result:

I now have definite proof that people play my games! And I’m actually very surprised at how frequently my games are played. It’s pretty neat to see when one person plays my game a lot for several days. It’s also interesting to see times when there are no tweets, and then suddenly for a few days there are lots of tweets from lots of different people. It brings a smile to my face each time I see a new tweet and realize that someone else is playing a game that I made.

If you’d like to see or follow my Twitter bot, it can be found here: @DeozaanGames

Here are a few tweets that have been made since the bot first went live on April 12, 2014:

What I Learned:

I quickly saw what I considered flaws in my initial plans for fun tweets, and over the months since I introduced the feature, I’ve worked to improve the messages my games will tweet.

Below are some tips on how to improve the tweeting experience.

Add Variety

Make sure you have a lot of variety in the pre-defined messages. It gets old very quickly always seeing “JoeX died lol!” tweets over and over.

It gets old fast, right?

I’d recommend at least about 10 different messages per “status” to choose from. For example, 10 different game over messages, or 10 different high score messages.

This might not apply if your message is already highly variable, such as “Bob got killed by X” where X could be 50 different things. Even still, it might be nice to see some variety such as “Bob got killed by X” and “Bob was murdilized by X” or “Bob’s guts were smeared all over the place by X” etc.

Don’t Rely on Player Input

I thought it would be cool to include the player’s names (as entered for the high score table) in the tweets for all the messages, such as when they die, got a game over, or got a high score. But I quickly learned that a lot of my players don’t bother to put anything in for their name in the high score tables:

I tried to fix this by making the game use “Someone” as the name if they left it blank, but it seemed a little strange, especially if “Someone” was placed in the middle of a sentence:

Ultimately, I just came up with a bunch of different messages that could be displayed that didn’t use the player’s name anywhere:

Another common problem is that sometimes the player will just enter gibberish:

I don’t really know how to fix that one, but gibberish is better than nothing, I guess.

Make it Interesting/Humorous

I tried to lighten the mood and make things fun(ny) by including some haikus, pop-culture references, or memes.

Consider Special Circumstances

One thing I did was tweet whenever someone got a game over or quit because I wanted to have at least one tweet per game played. But I didn’t take into consideration the fact that some people might start a new game and then immediately quit, until one day, just minutes apart, the following tweets were made:

Oops! I guess maybe a player was trying to quickly earn the achievement for playing 100 games, not realizing that quitting doesn’t count toward that goal. I quickly updated the game so that it wouldn’t tweet game overs/quits if the player didn’t get any points.

Conclusion:

Wow, did you really make it this far? Thanks for reading this! I hope you’ve found it useful. Please let me know if you use or adapt my work to implement your own Twitter bot!

Also, you’re welcome to try out my games for yourself if you’d like to contribute to the tweets my bot makes. As of this writing, only Blasteroids and Be Tiny, World! send out tweets related to the game. But I intend to include the functionality in all my future games. I even meant to include it in my Ludum Dare 29 game, It Came From… Beneath! but I didn’t have time to implement it before time ran out.

If you have any questions or other feedback, feel free to leave a comment on this post or contact me on Twitter @Deozaan.

Thanks again.

The files:

All the files necessary can be found at my Tweeter gist.