Twine Tutorial: How To Use the Share Menu in SugarCube v2

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.

StoryShare passage in Twine
This is really all it takes to get started…

The button, when pressed in your game, shows the player a little modal pop-up that’s… a bit underwhelming, all by itself.

Default Share menu in Twine with SugarCube v2 story format
…but this is all you get out of the box.

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:

In Twine, we add a couple dummy links to our StoryShare passage just for looks.
And, hey, the end result is already 5% better!

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.

Twitter

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.)

Facebook

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:

https://www.facebook.com/sharer/sharer.php?u=<your  URL>&src=sdkpreparse&display=popup

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:

Here are our finished social media share links to Twitter and Facebook, defined inside the StoryShare passage in Twine.

And here is the result your players will see after clicking the share links in your Twine game:

Sharing to Twitter! Here is a tweet with the link, text, and hashtag I defined, as well as a tag to my Twitter handle. RIP my menchies
And here is our share to Facebook. Notice it’s up to the user to write a message to go with the status update. Also, the URL I’m sharing doesn’t have a featured image defined right now, so you can see how boring this looks. Better fix that.

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!

Advertisements