Category: Coding

Converting Twine 2 Stories to Android APK Apps for the Google Play Store

4 Comments

In our last part you learned how to write a Choose Our Way tale with Twine 2, and share it on a website so that it could be shared with people outside of the classroom.  Now you will learn how to transform your Twine 2 story into an Android APK App file which can be played on Android phones and tablets.

Examples:

 

Examples of apps made using this method can be found at: Sammi’s Quest: Google Play Store

A Free Demo can be downloaded to your Android Device Here: Sammi’s Quest: Vol. 1 – The Wandering Ogres (Demo)

The Full Version can be purchased for your Android Device Here: Sammi’s Quest: Vol. 1 – The Wandering Ogres (Full Release)

CONVERTING TWINE 2 STORIES TO ANDROID APK APPS FOR THE GOOGLE PLAY STORE – A Step by Step Tutorial

Introduction:

This tutorial will teach you how to create a Choose Your Own Adventure Android App.  It’s easier than you could imagine.  To create your app you will need to use:

  • Twine 2
  • Adobe PhoneGap Build

While it may seem difficult, at first, you should be able to build your first Android App in less than two hours.

Creating your story with Twine 2

Twine 2 is a web-based Choose Your Own Adventure program.  You can access it here:  https://twinery.org/2/

The Basics of Twine 2

This tutorial is focused on converting a finished Twine 2 story to Android APK, however I will include some basic information for creating a Twine 2 story.

  1. When editing your first page, you create options by writing [[Go to the fountain]]. This will create a link reading [[Go to the fountain]] and a new page called Go to the fountain.This is not the best way to do things, as you may want to have a number of options send the user to that location.
  2. If you want the displayed link to look different than the page reference you need to write it like this [[Go to the fountain|Fountain]]. This will display the text “Go to the fountain” as a link to a page titled “Fountain”.This allows you to have another page reading [[She ran to the fountain|Fountain]] that also takes the user to the same location.
  3. For more information about creating a Twine 2 story feel free to read this tutorial: http://www.adamhammond.com/twineguide/

Once you have created your Twine file select Publish to File. This will download a file titled StoryName.html  This file is your complete story.  You can open the file and play through your story in a web browser.

If that’s all you want, you’re good to stop.  However, if you want to convert it to an Android APK keep reading.

Preparing your Story for Phone Gap

Once you have your StoryName.html file you need to prepare a folder for it.  This folder will eventually be Zipped, and uploaded to Adobe Phone Gap Build for conversion to APK.

  1. Create a directory named WWW. Do this by Right Clicking on your desktop, selecting New/Folder, then naming it WWW.
  2. Copy StoryName.html to your WWW directory.
  3. Rename StoryName.html to index.html. You can do this by right clicking the file, and selecting Rename.  Then, type in index.html
  4. Finally, you will need to create a config.xml file. This is what provides the information about your app to Android.  To do this, right click in your WWW directory, and select New Text Document.  Leave it named New Text Document.txt
  5. Open the file, then copy and paste the text below into that document (you do not want to copy the numbers on the left hand side):
<?xml version='1.0' encoding='utf-8'?>
<widget id="com.YourName.AppName" version="1.0.0"   
        xmlns="<a href="http://www.w3.org/ns/widgets">http://www.w3.org/ns/widgets</a>"
        xmlns:gap="<a href="http://phonegap.com/ns/1.0">http://phonegap.com/ns/1.0</a>">
    <name>Your App Name</name>
    <description>
        Replace this line with a description of your app.
    </description>
    <author email="your@email.com" href="<a href="http://your.website.com/">http://your.website.com</a>">
        Your Company Name
    </author>
    <content src="index.html" />
    <access origin="*" />
    <preference name="DisallowOverscroll" value="true" />
    <preference name="android-minSdkVersion" value="14" />
    <preference name="phonegap-version" value="cli-6.3.0" /> 
    <preference name="orientation" value="default" /> 
</widget>

Modifying the config.xml

You will need to add your own personal information to the config.xml file.  Make the following changes:

  • On line 2 change com.YourName.AppName to your information. (i.e. com.JonSmith.CoolAlienStory)
  • On line 5 change “Your App Name” to the name of your app.
  • On line 7 change “Replace this line with a description of your app.” to a description of your app.
  • On line 9 change “your@email.com” to your e-mail address
  • On line 9 change “http://your.website.com” to your website link, or leave blank.
  • On line 10 change “Your Company Name” to your company name.

Final steps in Adobe PhoneGap Preparation

  1. Next select File and choose Save As. Name your new file xml  This new file must be saved in your WWW directory.
  2. Finally, navigate back so you can see your WWW directory icon.
  3. You need to ZIP this WWW directory. To do that right click the folder icon, and choose Send To then Compressed (zipped) folder.  This will create WWW.ZIP
  4. You will need to upload this WWW.ZIP folder to PhoneGap Build.

Using Adobe PhoneGap Build

Once you have prepared your ZIP file, it’s time to upload it to Adobe PhoneGap Build, and convert it to an app.  To do this please follow the next few steps.

  1. Navigate to https://build.phonegap.com
    This is the website that will convert your file to an app.
  2. Click “Sign In” in the top right, then select “Sign up for a new account”.
  3. Choose “Completely Free” then select an option to create an account. I recommend using Google as your sign in option.
  4. Once you have signed in, you will be taken to the main page. There you will see an option called Upload a .zip file.  Click on this, navigate to your zip file, and it will upload.
  5. Once you have uploaded your ZIP file, you will notice a number of things are automatically filled out. (The name of your app, the summary of it, etc.)
  6. You will now see an option called Ready to Build. Click on this button and the file will build.  This can, sometimes, take a while.
  7. You will notice a QRC when the file is built. This QRC can be used to link other people to your APK file.  You will also notice a little android icon over the Update Code button, or a blue button with a down arrow beside the word APK.  Clicking on this icon will download the APK file, which can be installed onto android devices.

Updating your Story

If you want to change something in your Twine 2 story, you can re-edit it using Twine 2, and then Publish to File again.  Once you have exported the new StoryName.html file you need to:

  1. Override the previous html file in your WWW directory.
  2. Re-ZIP the entire directory.
  3. Navigate to Adobe PhoneGap Build and click on Update Code.
  4. Select the new ZIP file you just created.
  5. Click Upload and your new APK will be created.

Note: You may find it helpful to create a new .ZIP file, rather than overriding the original, so you don’t lose copies of your previous versions.  I suggest dating each ZIP file as YYMMDD.TIME – StoryName (i.e. 171011.1344 – Sammi’s Quest)

Common Errors

  1. Ensure that there are no blank lines at the top of your CONFIG.XML file
  2. If you have added the code for app icons, ensure the icons are in the correct directory
  3. Confirm that the icons are the correct size
  4. Check to see if you have renamed your story file to html
  5. Make sure you have a xml file that conforms to the requirements
  6. Double check that you have added a png file that fits the required size

 

Personalizing your App

There are a number of ways you can personalize your application.  The easiest ways to do this are by adding a Splash Screen that displays when you start up the app, and by adding a personalized icon to be displayed on your Android device.

Adding a Splash Screen

  1. To create a splash screen use any photo editing software to create an image file that is exactly 360×480 pixels. Save this file as png in your WWW directory.
  2. Add the following lines to CONFIG.XML before </widget>
    <plugin name="cordova-plugin-splashscreen" source="npm" spec="~3.2.1" />
    <preference name="SplashScreenDelay" value="3000" />
    <preference name="ShowSplashScreenSpinner" value="false" />
    <preference name="FadeSplashScreen" value="false" />
    <preference name="SplashMaintainAspectRatio" value="true" />
    <preference name="SplashShowOnlyFirstTime" value="false" />
    <splash src="splash.png" />

Adding an Icon

  1. To create an icon for your application you will first need to create a folder named res in your WWW directory
  2. Inside the res directory, create a new directory named icon.
  3. Inside the icon directory, create a new directory named android.
  4. Now you will need to create your icon file.
  5. To create your icon, first create a high resolution file using an image editing program. Create the icon to be 1024×1024 pixels.  Save this file as png
  6. Direct your webbrowser to https://resizeappicon.com/
  7. Select Upload file, and wait for the icon to upload and be displayed.
  8. Scroll down the page until you see the heading Android. Click on All.  This will place check marks beside all the Android icon files.
  9. Scroll to the bottom of the file and click Download Selected.
  10. This will download and AppIconResizer ZIP file. Open this zip file, and move all the png files from the zip to your WWW/res/icon/android
  11. Since your config.xml already points to this directory to find the icon files, once you copy these files you’re ready to re-ZIP your WWW directory, and upload it to PhoneGap Build.
  12. Add the following lines to CONFIG.XML before </widget> :
<platform name="android">
     <icon density="ldpi" src="res/icon/android/ldpi.png" />
     <icon density="mdpi" src="res/icon/android/mdpi.png" />
     <icon density="hdpi" src="res/icon/android/hdpi.png" />
     <icon density="xhdpi" src="res/icon/android/xhdpi.png" />
     <icon density="xxhdpi" src="res/icon/android/xxhdpi.png" />
     <icon density="xxxhdpi" src="res/icon/android/xxxhdpi.png" />
</platform>

A little bit More

There may be a few more things you need information about.  Hopefully this section covers them.

Creating iPhone Apps

You’ve done most of the heavy lifting already.  All that is required to make this an iPhone app is to add a little bit of information to the XML file.  To learn more about that process read the following website: http://docs.phonegap.com/phonegap-build/configuring/preferences/

Downloading your APK to an Android Device.

You can select the “Download” option to save the APK file to your computer, and then transfer it to your device if you want.  However, there is a far easier way.

You can scan the QR code with your phone or tablet, and it will download your app.

If you don’t have a QR scanner on your android device you can download one here: https://play.google.com/store/apps/details?id=me.scan.android.client&hl=en

Navigate on your device to the download directory, and install the APK file. You can now enjoy your story in app form, and distribute it to your friends.

Hosting your App on the Google Play Story

If you’d like to host your story on the Google App store, you will need a developer account. For information on that can be found here: http://support.andromo.com/kb/distributing/how-to-put-your-app-in-google-play or by reading the official Google documentation.

Long Story Assignment

Preparing for the long story assignment, I suggest you familiarize yourself with the snowflake method of writing. I created a handout that uses the snowflake method, adapting it for the needs of a Choose Our Way tale.  Once students have planned their story using this method, they can complete the assignment.

Requirements

  • Be between 2000 and 5000 words long
  • Have at least six endings
  • Have at least ten pages where the reader can choose a direction
  • Be converted to Android APK using Adobe PhoneGap

Handout: The Snowflake Method for COWtales

Handout: Twine 2 Long Story Assignment

Next Steps

Now that you know how to use Twine 2, and convert Twine 2 files to Android APKs you’ve reached the end of these tutorials.  If you’d like information on how to upload your app to the Android Play Store, the official documentation can point you in the right direction.

In the next, and final part, you can access all the handouts that have been posted along the way.  You are free to distribute them for non-commercial use.

PART 1: Introduction to Choose Our Way tales

PART 2: WRITING CHOOSABLE PATH STORIES WITH
STUDENTS

PART 3: USING TWINE 2 TO CREATE DIGITAL CHOOSABLE PATH STORIES

PART 4: CONVERTING A TWINE 2 STORY TO ANDROID APP APK USING ADOBE PHONE GAP

PART 5: Twine 2 / CHOOSE OUR WAY DOWNLOADABLE RESOURCES