I wasn’t able to find a guide to using the “Share” menu in Twine’s SugarCube v2 story format, so I thought I’d write one up for others who want to use it but don’t know where to begin.
(Please note: this tutorial assumes that you know the basics of working with Twine and SugarCube 2; if you don’t, check out this great tutorial by Allison Parrish.)
SugarCube v2 has a special passage named StoryShare, which, when added to your Twine game, will automagically give you a nifty “Share” button on the game’s sidebar navigation.
The button, when pressed in your game, shows the player a little modal pop-up that’s… a bit underwhelming, all by itself.
The documentation doesn’t give us much to go on aside from letting us know the option is there. So what exactly do you need to put in the StoryShare passage to actually make it work?
It turns out that getting basic functionality into that menu is pretty simple. To begin, let’s go into Twine and fill the passage with a couple dummy links to Twitter and Facebook to see what comes out:
So far so good, but when’s the magic gonna happen? If you use your favorite search engine to look for “social media share buttons,” you’ll find some automated tools that can point you in the right direction, but you’ll quickly discover that many of these tools rely on problematic things like iframes or require embedded scripts that aren’t really necessary. I’ll demonstrate how to construct do-it-yourself share links for Twitter and Facebook. Those happen to be the platforms I use most, but this should work in a similar fashion for any platform you want to share to.
For Twitter, the secret sauce is making a post to Twitter’s “tweet” Web Intent API. You’re going to make a link with this anatomy:
https://twitter.com/intent/tweet?url=<your website>&text=<your message>&via=<your Twitter handle>&hashtags=<your hashtags>
To break this down: everything between angle brackets (“less than” and “greater than” signs) you’ll replace with your own values. (Don’t include the angle brackets!) To get technical, every item that appears after a question mark (?) or ampersand (&) is a query parameter, or a key/value pair through which you submit information to Twitter’s API. Twitter knows that whatever value you submit for “url” is the URL of the thing being shared, for example, and whatever value you supply for “text” is the message you want in the tweet.
If you read through the API documentation, you’ll see that the values for url and text need to be URL-encoded, which means special characters that have a particular meaning to web server software are transformed so they’re not misinterpreted. This might sound complicated, but worry not, because reading this explanation is the hard part. It’s easy to find a URL encoding tool that will do this for you. Copy your URL or text, paste it into the tool, hit “encode” et voila, you’re ready to copy the encoded result and paste it into your share url as a parameter value.
The “via” and “hashtags” parameters are optional, but if you want to get a Twitter notification when somebody shares your Twine game, be sure to include your Twitter handle! (Note: The @ and # signs are not required here; Twitter will add them for you.)
Sharing to Facebook is simultaneously easier and more complicated than sharing to Twitter. As of this writing, Facebook has clamped down hard on the ability for third parties to post to personal timelines. It’s still possible to generate an easy “share” link for people to spread the word about your Twine game, but the amount of information you can send along with your share request is very limited — basically, you’ll only be able to send a URL. Due to how external links are displayed on the Facebook timeline, you probably want to choose a blog or webpage URL that has the ability to define a featured image, to really make the post stand out.
The anatomy of a Facebook share URL looks like this:
Similar to Twitter’s API, Facebook lets you pass as a query parameter the URL to share, here sent with the key value “u.” Unlike Twitter, Facebook does not allow you to send a predefined message — it’s up to your user to write something (hopefully something good!) about your game before they post your link to their Facebook profile. You can see we’re also sending the query parameters “src” and “display,” with values provided by Facebook.
You can read a bit more about Facebook’s sharer API here. (See “URL Redirection” under “Advanced Topics.”) Note that according to the documentation, a Facebook Developer app ID is required when making a web request to the sharer API, but in my testing it seems to work just fine without one. (If necessary, getting a Facebook app ID is easy — see the Facebook developer center to get started.)
Putting It All Together
Now that we’ve seen how to construct those nifty share links, here’s what your StoryShare passage will look like inside the Twine editor:
And here is the result your players will see after clicking the share links in your Twine game:
With any luck, your players will be happy to share the news about your game, now that you’ve made it so easy for them!
Was this tutorial helpful for you? Please send me a quick note to let me know!