Create an AppaApps Photo App! Beta test site

Last updated on 2018-Apr-09.

The learning app creation tool available from this site is presented under Creative Commons License 4.0 by Coreliu. Coreliu is a Script City Ltd brand.

If you can create an annotated slide show, then you can create an Android App just like Cars, Cranes, Trucks, Trains which you can publish and distribute as you wish. Here is how:

 
1    Things you will need to create an interesting app
2        Knowledge
3        A Computer and an Android Phone or Tablet
 
4    How to write an AppaApps Photo App
 
5    Detailed Instructions for creating an AppaApps Photo App
6        Create a free account on GitHub
7            Authorize AppaApps to access your GitHub account
8            Set up your notification preferences
9            Set up your email preferences
10        Create a new repository on GitHub to hold your apps
11            Security Disclaimer
12            Authorize AppaApps to collaborate with you
13        Write your app
14            Add some interesting photos to the images/ folder
15            Write the facts for each photo
 
16    Layout and meaning of sourceFile.txt
17        Commands
18        Keywords and values
19        Compressed Syntax
20        Matching names
 
21    Distribution
22        Upload a movie of the app to YouTube
23        Put a link to your app on your web site
24        Upload your app to Amazon App Store
25        Upload to Google Play
 
26    Notifications and Rewards
 
27    Zoom and Pan
 
28    Useful links
 
29    Processing Summary

 

 

Things you will need to create an interesting app

"Tutta la nostra conoscenza ha le sue origini nelle nostre percezioni" - Leonardo Da Vinci

"Die Grenzen meiner Sprache sind die Grenzen meiner Welt" - Ludwig Wittgenstein

 

Knowledge

The most important thing you will need to write an interesting app is interest and knowledge about a subject that you can illustrate with photos and describe with facts. For example: if you are know a lot about horses; have access to lots of illustrative photos of horses doing interesting things; and you can describe the important features of these photos in a few succinct words; then you have a good basis for writing an interesting app about horses. Or perhaps jet aircraft. Or growing roses.

The app generation process synthesizes speech from your facts, then packages the speech together with your photos to create an immersive Android app. The app teachs students by showing them the photos, gradually introducing the spoken facts, then using the facts as questions for which the student must choose the matching photos.

 

A Computer and an Android Phone or Tablet

You will need a small amount of computer equipment:

  1. A computer with an Internet connection
  2. An Android device if you want to play the app as a native Android app on a phone or tablet

 

 

How to write an AppaApps Photo App

To create an app in the AppaApps format follow these instructions:

  1. Create a free account on GitHub if you do not already have one.
    1. Authorize AppaApps to access your GitHub account.
    2. Authorize AppaApps to email you notifications via GitHub.
    3. Set up your email preferences
  2. Create a new repository on GitHub to hold your apps.
    1. Security Disclaimer
    2. Authorize AppaApps to collaborate with you
  3. Write your app
    1. Put some interesting photos that you wish to display into a folder called images/ in your new repository.
    2. Write down the facts that you wish to present for each photo by saving the facts as text in a file called sourceFile.txt in your new repository.

GitHub will then tell AppaApps to generate the app for you: GitHub will send you a notification via email when the app is ready for you to download and play.

You will be able to see all the notifications related to your repository under the Issues tab in the top centre left of your repository's home page:

and also in your email, depending on how quickly your email updates (possibly under Spam):

If you get stuck, create an issue against your repository by clicking on the word Issues in the top centre left of your repository's home page:

and the push the green "Create Issue" button. AppaApps will be pleased to collaborate with you to resolve the problem.

 

 

Detailed Instructions for creating an AppaApps Photo App

 

Create a free account on GitHub

Go to GitHub and follow the instructions to create a free account, keeping the alert below in mind:

Please make sure that your userid name on GitHub starts with an upper or lowercase letter in the range A to Z and thereafter only contains upper or lowercase letters A to Z and/or digits 0 to 9. The inclusion of any other letters will cause the app generation process to fail.

Thus userid: user1 will work well.

While userids: 1user, user 1, user𝝰 will all fail miserably.

Authorize AppaApps to access your GitHub account

The following actions will authorize AppaApps to write files into repositories in your account, to manage the web hooks which will connect your repositories to AppaApps and to create issues to tell you what is happening.

Click the following link to go to the GitHub Tokens page for your account.

You will see:

Click on Generate New Token in the top right corner.

Give the token a convenient name of your choosing.

In the first box below the name field, select: repo - Full control of private repositories

In the fourth box down chose: admin:repo_hook

At the bottom of the page press the green button: Generate Token

You will then see your new token on a pale green background.

Please send this token and the userid of your GitHub account by email to philiprbrenan@gmail.com who will install it on AppaApps allowing philiprbrenan@gmail.com to generate apps for you. The easiest way to do this is to copy the token to your clipboard by clicking on the clipboard sign next to it and then pasting it into the email asfter your userid. Please include the following statement in the email:

I understand that by sending philiprbrenan@gmail.com this token I have compromised the security of all the repositories under the userid associated with this token: I can and do absolve philiprbrenan@gmail.com from all responsibility for maintaining the security of this data because it contains nothing confidential and the data is fully backed up elsewhere.

You can withdraw the permissions associated with the token or change them at any time with immediate effect by returning to this page.

Set up your notification preferences

It is very helpful to have GitHub email you as events occur in your repository. To enable this, click the following link to go to the: GitHub Notifications page for your account.

You will see:

Click on Automatically watch repositories at the top and Include your own updates right at the bottom.

Set up your email preferences

If you wish to ensure that your email address is always kept private: go to the email settings page and check the indicated items below.

 

Create a new repository on GitHub to hold your apps

You are now ready to create a new GitHub repository to contain your apps and connect the repository to AppaApps to generate the Android versions of these apps for you.

Push the "plus" sign at the right hand end of the title bar and choose new repository from the menu.

Security Disclaimer

When you create your repository you can select public or private for the type of repository (or repo). We advise you to select public because:

  1. Public repositories are free on GitHub

  2. Apps created from both public and private repositories will not remain private on publication because you have no control over the distribution of your apps when you publish. Even if you publish on restricted circulation, the people you publish to might redistribute your apps.

  3. We cannot guarantee the security of data exchanged between you and AppaApps: Recent global IT security breaches (i.e. The Pentagon, the NHS, the UK Information Commissioner and UK council websites) tell us that in the world we live in, no IT system or website can be 100% secure. AppaApps works to industry standards of information security but this can not guarantee the security of your app content prior to publishing. Any IT system can be hacked!

Choose a simple, short name for your repository: please make sure that the name of the repository contains only letters and numbers drawn from a through z, A through Z, 0 through 9 and _ (underscore). The name must start with a letter and must not contain spaces, commas or any other punctuation characters else chaos will ensue.

Choose the option of initializing the repository with a README - which once created can be left blank for the moment. At this point you can skip the other options: GitIgnore and choosing a licence.

Press the green Create Repository button to create the repository.

Authorize AppaApps to collaborate with you

Once you have created a repository on GitHub and before you add any files to it, you should invite philiprbrenan@gmail.com to be a collaborator by clicking the word Settings in the top centre right of your repository's home page, then click Collaborators at the top of the left side bar:

Enter AppaApps as the name of the collaborator in the search box and push the button: Add collaborator. AppaApps will now be able to answer any questions you pose by creating issues on GitHub. To create an issue, click on the word Issues in the left top corner of your repository's home page.

AppaApps will respond to your invitation to collaborate by connecting your newly created repository to AppaApps and creating some useful files and folders in your new repository. You will receive a notification from GitHub once this work has been done; usually it takes just a few moment.

Once notified by AppaApps that the web hook has been created, you will be able to see the web hook connecting your repository to AppaApps by clicking as follows:

Go to repository settings:

Click on web hooks to get:

You can click on the web hook to see its details:

You can also see when the web hook last notified AppaApps at the bottom of the image above.

You can delete this web hook at any time to disconnect your repository from AppaApps if you wish to end this collaboration.

 

Write your app

If you have received notification from AppaApps that the web hook is in position as described above, you can then start to load your repository with images and text as described in the next sections to actually create your app.

Add some interesting photos to the images/ folder

Now that you have a repository ready to go you can start development of your app. The first thing to do is to find some of photos that illustrate the points you wish to make and load them into the images folder in your new repository. To do this, click on images:

which will take you into the images folder.

Click on the upload files tab to get:

Click on the choose your files link:

On this page you can choose the files you wish to upload.

You will probably find it easiest to load a small number of images first, say three or four, so that you can create a prototype app and then improve it by adding more photos as you see fit.

Every time you save a photo into your repository AppaApps, being a collaborator, will receive a message indicating that this has been done. AppaApps responds to this message by creating or updating the file sourceFile.sample.txt in your repository. This file shows what a very basic app using these photos you have supplied might look like and so serves as a useful template for further development.

Write the facts for each photo

You should write the facts for each photo in a file called sourceFile.txt. You can have as many of these files as you wish in your repository as long as they are in separate folders as you can see in: The Numbers from 0 to 100 which uses one folder to hold the sourceFile.txt file for each language.

You might find it helpful to use a text editor such as: Geany to edit sourceFile.txt as in:

Each time you save a new version of any sourceFile.txt into your GitHub repository, AppaApps will try to generate an app from the definition held in the file and will notify you of the results of the generation process via GitHub issues and email. If your sourceFile.txt looks good, an issue will be immediately created saying so. The app generation process will then synthesize any speech needed and combine it with the photos in an Android Package .apk file suitable for installation on any Android device.

If the app generation process fails you will receive an issue via GitHub that describes the problem allowing you to fix your sourceFile.txt and continue.

An easy way to create the sourceFile.txt file is to copy the contents of sourceFile.sample.txt which is a sample version of this file created for you by AppaApps each time you save a photo into your images folder.

Here is a sample listing of the files in a GitHub repository:

You can see the images folder on the first line and the files sourceFile.sample.txt and sourceFile.txt on the last two lines.

Here are the first few lines of a typical sourceFile.sample.txt file:

app GoneFishing   = DDD
  maximages = 6
  icon      = https://avatars1.githubusercontent.com/u/36601762?v=4
  author    = lspfa
  email     = 36601762+lspfa@users.noreply.github.com

# Details of photo Blacktip shark
photo Blacktip_shark = Title of Blacktip shark
  url = Blacktip shark.JPG

fact Blacktip_shark.1 = First fact about Blacktip shark
fact Blacktip_shark.2 = Another fact about Blacktip shark

# Details of photo Brown Trout
photo Brown_Trout = Title of Brown Trout
  url = Brown Trout.jpg

fact Brown_Trout.1 = First fact about Brown Trout
fact Brown_Trout.2 = Another fact about Brown Trout

The file: sourceFile.txt will be processed by a computer at AppaApps to create your app. Consequently, the information in this file has to be organized in a specific manner so that it can be processed by a computer rather than an intelligent human being.

A complete definition of the format of this file is given in section Layout of sourceFile.txt.

For your first app the easiest thing to do is use sourceFile.sample.txt as an example and type the facts that you are going to use over the text "First fact about" and "Another fact about" and save the results in file: sourceFile.txt in your new repository.

You are bound to make mistakes in the process of generating an app, but such mistakes are not fatal because you can always try again. If AppaApps cannot generate an app for you from the information you have provided in sourceFile.txt, then AppaApps will create an issue on GitHub explaining the problem and you will be notified of this by email. You can use this information to correct your sourceFile.txt. When you commit this file to GitHub, AppaApps will try to generate the app again for you.

If you get hopelessly stuck, just create an issue yourself by clicking on the word Issues located in the top left corner of the home page for your repository (just under then name of your repository) and someone at AppaApps will be pleased to respond if AppaApps has been invited to act as a collaborator on your app.

AppaApps will attempt to regenerate your app each time you commit, that is: save a new version of sourceFile.txt to your repository on GitHub. You do not need to perform any other action other than waiting for the notification that GitHub will send you once AppaApps has finished regenerating your app.

If you wish to receive such notifications by email, then you should make sure that you are watching your repository as described in: Set up your notification preferences.

Or you can look in the issues section of your repository and pick up the notifications from there as they come in.

If AppaApps successfully creates an app for you from the photos and facts that you provided in sourceFile.txt, the email from GitHub will tell you where to go to download your app from the cloud to your phone and where you can play the app in your web browser. This allows you to try out the latest version of your app immediately and make any improvements you think desirable after admiring your app in action.

 

 

Layout and meaning of sourceFile.txt

This repository contains the sourceFile.txt for this app.

Please feel free to copy and modify it as you wish.

 

Commands

An app description tells AppaApps how to create an AppaApps Photo App for you using commands in a well defined language. This language has been designed to be simple to code by non technical authors yet powerful enough to express the information required to fully define an AppaApps Photo App.

An app description starts with a single app command followed by additional photo and fact commands. The action of each command is defined by the values of its associated keywords. The commands and their keywords tell AppaApps how to create the app for you. You can add notes to yourself by coding a # sign followed by the content of your note up to the end of the same line.

CommandDescription
app The first command should be an app command whose keywords specify global values for the app.
photo For each photo that you want to include in an AppaApps Photo App, you should code one photo command to give the photo a name and title and to tell AppaApps where the photo is located on the Internet so that the photo can be retrieved and displayed in the app.
fact Use the fact command to provide facts for each photo. These facts will be used to teach and then test the users of the generated app.

 

Keywords and values

The action of each command is modified by its following keyword = value pairs, coded one pair per line. Upper and lower case are interchangeable in keyword names and underscores _ are not considered significant, so, for example, you can code the keyword:
fullPackageNameForGooglePlay
as:
full_package_name__for___Google______play
if you wish.

Keywords cannot have spaces in them, so:
full Package Name For Google Play
would not be regarded as a keyword causing the app generation to fail.

Values occupy the remainder of the line. Leading and trailing whitespace around the value will be ignored. Spaces are allowed inside the value so:
description = Robot descending from the sky
would work well as a keyword value pair.

You can turn a keyword = value line into a helpful comment that will be ignored by AppaApps by preceding the line with a # as in:
# maxImages = 12

Later on, if you change your mind and want AppaApps to take note of this information, you can remove the # to bring the keyword and its associated value back into play.

Here is a list of the current keywords, their possible values and what happens if you code them:

CommandKeyRequiredDescriptionDefaultPossibilities

app

Outline description of an app

author

author

The name of the person who wrote this app which should be the name of the repository containing the app. Thus if the name of the repository is:

philiprbrenan/GoneFishing

then the author of the app will be:

philiprbrenan

The app generation process will inform you of the correct name if you get it wrong.

description

A slightly longer description for the app often used for the short description on Google Play.

email

The email address of this app so that students have somewhere to send suggestions, corrections or complaints

emphasis

Generate slower, more emphatic speech for some items so that a student who did not understand the normal fast speech version can be given a slower, more comprehensible version on redirect.

Code a number for the value of this keyword: any phrase that has fewer characters than this number will cause both normal and emphasized versions of the speech to be generated. Phrases longer than this number will only cause a normal version of the speech to be generated.

If you omit this keyword or code a value of zero then only normal speech versions will be generated.

enables

The names of apps that the user might enjoy playing after completing this app. If the student appears to have mastered all the material in this app the app will start playing one of these apps instead.

fullNameOnGooglePlay

The full name of the the app on Google Play. This is set by default for you to the standard value of: com.appaapps.photoapp.<github path to your sourceFile.txt>

Use this keyword to change this name to something else in the unlikely event that you want to use a different name on Google Play for your app.

help

Use this keyword to specify the URL of a web page where the student can find more information about the app, its purpose, how to use it, who wrote it, the sponsoring organizations, their contact details etc.

See also: the app.title= keyword and the app.logoText= keyword.

icon

If the URL starts with https?:// then this is the location of the icon image on the World Wide Web from whence it will be copied and scaled to the right size. If the URL starts with github: it comes from the specified repository on GitHub. Otherwise it is the name of the file in the images folder in the GitHub repository for this app which contains the icon for this app.

imageFormat

By default use the jpx (jpeg extended) image format to display photos at high resolution on the Android. Your jpg and png images will be automatically converted to use the jpx format by the app build process so no action is required of you to use this format.

If you do not want to use jpx, code this keyword with a value of jpg to instruct the build process to use the jpg format to represent images. If you supply photos in the png format the build process will automatically convert them to jpg for you for use on Android.

jpxjpg

language

The two character code which describes the language this app is written in. All the voices that speak this language will be used to speak the app unless the app.speakers= keyword is used to specify the speakers that you actually require.

The one exception to this rule is English, which is spoken by just Amy and Brian unless you specify otherwise.

ency da de es fr is it ja ko nb nl pl pt ro ru sv tr

levels

The number of levels in the game. Each photo has a level and only comes into play when the student reaches that level of play. You can specify the level for each photo manually using the photo.level= keyword. Or you can use this keyword to specify the number of levels in the game and have the app generation system allocate photos to each level based on their position in sourceFile.txt.

If the number of levels is not specified it defaults to one: in this case all the photos are in play as soon as the app starts.

12 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100

logoText

When the app starts for the first time it downloads its content from the Internet which might take a moment or two. The app covers any delay by showing the name of the app and the name of the sponsoring organization on the splash screen.

Use this keyword to show a small amount of text identifying your organization. The app will scale this text to fit the screen, so if you want the name to be in large visible letters it must contain only a few characters. Conversely, long names will be shrunk down to fit the display and will probably be unreadable.

See also: the app.title= keyword and the app.help= keyword.

maxImages

The maximum number of images to show in one selection at a time in the app: choose a value that reflects how many images a competent student might reasonably scan in 30 seconds

122 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24

maximumRaceSize

The maximum possible number of questions that can occur in a race. Otherwise, the default is the total number of photo commands in the app. However, the student will only be faced with the maximum possible number of questions once they have made considerable progress through the material in the app as races are restricted to information that the student has already encountered.

name

name A short name for this app which matches the path in your repository to the relevant sourceFile.txt with all the forward slashes replaced by dots. Thus, if the full name of the source file in the repository is:

philiprbrenan/GoneFishing/l/en/sourcefile.txt

then the name of the app will be:

GoneFishing.l.en

The app generation process will inform you of the correct name if you get it wrong.

ordered

The next item to be presented to the student will be chosen in some kind of order if this keyword is coded:

always
The items tend to be presented in the order they are written in the app definition file.
finally
The opposite of initially. The items are initially presented in random order but the order is applied ever more strictly as play proceeds.
initially
As with always, the items are initially presented in order, but the order is applied less and less strictly as play proceeds.
never
The opposite of always. The order of the items is not considered to be important. This is equivalent to not coding this keyword or commenting it out.
neveralways finally initially

prerequisites

The names of apps that perhaps the user ought to play first, listed in play order separated by spaces. If the student does not appear to be making much progress with the existing app, the app will start playing one of these apps instead.

rightInARow

The number of questions the student must answer correctly in a row to trigger race mode.

In normal play the student receives new items of information every time they answer a question correctly the first time the question is posed; otherwise answers are provided for questions that the student is unable to answer correctly.

During a race, no new items of information are presented: the race continues as long as the student does not make too many mistakes or until all the items that the student has previously identified correctly have been presented. Race mode questions are presented with less delay than normal questions.

The race starts with well known items and with quiet background music. As the race proceeds, the music gets louder and the questions become more difficult as measured by how often the student has correctly identified the items in the past.

The objective of a race is to set a personal best time for completing a race through all the items in the app without errors.

At the end of race, the student is congratulated if they did not make too many mistakes. Play then reverts to normal mode.

72 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24

saveScreenShotsTo

Code this keyword in the unlikely event that if you would like screen shots taken in the app to be saved to a different GitHub repository. Code the GitHub user name, followed by '/', the repository name, optionally followed by a path which will be prefixed to the screen shot name.

This feature only works for the first two hours after an app has been created: after that the app plays normally.

screenShots

Screen shot mode is enabled if this keyword is present with any value or indeed no value. See: the photo.screenShot= keyword for full details.

See also the app.saveScreenShotsTo= keyword for details of how to specify an alternate repository in which to save screen shots.

speaker

If this keyword is present the app shows all the items in alphabetical order and says the item the user taps on. This is useful for app development and also if you have temporarily lost your voice

yes

speakers

The Ids of the voices to be used to speak the app or all the speakers in the language set by app.language= keyword.

test

Once you have created and published an app any further successful changes to this app will be transmitted directly to your active students. You might prefer to test the new version of your app first before making the changes publicly visible. To achieve this, code:

test = a description of the changes

Once you are satisfied with the changes you have made, you should comment out this keyword as in:

# test = a description of the changes

so that a succcessful generation will update all active copies of the app. You might find it helpful to update the app.version= to describe the new features in the app for posterity.

Please note that test apps will be deleted without notice from servers to free space if necessary.

title

title

The title for this app. This title will be displayed on the splash screen when the app starts for the first time and also under the icon representing this app on the student's phone or tablet. The title should be short, like a newspaper headline, as in:

Robots Invade London

See the app.logoText= keyword for details of how you can further modify the splash screen.

translations

Offer the user a choice of languages in which the app can be played. The sourceFile.txt files for the translated apps should be held in folders l/LCbelow the main source file for the app where LC is the two letter language code as shown in: speakers by code.

If all is chosen as the value of this keyword, then all the languages supported by Aws Polly will be offered.

allcy da de en es fr is it ja ko nb nl pl pt ro ru sv tr

version

A sentence describing what is in this version of the app. See all also the app.test= keyword.

photo

Description of a photo that illustrates one or more facts

aFewChars

aFewChars or url

One or two characters to display in the centre of the screen either in lieu of a photo or on top of a photo in alphabet and number games

level

The level of play at which the student is introduced to this photo and its related facts. If no level is associated with a photo or it has a level of 1 then the photo is introduced at the first level of play.

See also: app.levels= for an automated way of setting the levels of all the photos in the app.

12 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100

maps

Optional URL showing a map of where this photo was taken

name

name

A short name for this photo which will be matched against fact names as described in matching names.

pointsOfInterest

Indicate points of interest in a photo by coding the fractional coordinates of each point of interest as percentages from left to right and top to bottom of the photo separated by white space.

For example, the centre of the upper right quadrant is:

  75 25

The points of interest should be coded in order of decreasing interest, for example: if the centre is the most interesting point in the photo followed by the centre of the upper right quadrant, then code:

  50 50 75 25

All characters that are not the digits 0..9 will be converted to white space, which means that the above could be coded as:

  (50x50), [75 25];

Any missing coordinates will be assumed to have a value of 50

Points of interest are used (amongst other things) to centre screen shots, as far as possible, on the most interesting point in the photo.

say

The actual sequence that should be said by Aws Polly if this is different from the content of the photo.title= keyword.

Aws Polly uses: Speech Synthesis Markup Language which can be supplied using this keyword

Please note that the title of the photo is shown in text on some screens, so if this keyword is used the two might diverge.

screenShot

Code this keyword if you would like this photo to be made into a screen shot. You will need screen shots to upload your app to distribution web sites. This keyword gives you a convenient way to mark the photos in your app that would make the best screen shots.

To actually take screen shots you will needs to code the app.screenShots= keyword to temporarily enable screen shot mode. During screen shot mode, the app shows just the indicated items either centered on their first point of interest or moving so slowly that you can manually swipe the screen to take the shot when the photo is best presented on the screen.

By default the screen shots will be placed in your GitHub repository in:

  out/screenShots/photoname.jpg.

However, you can specify an alternate repository in to which screen shots are to be saved, see the app.saveScreenShotsTo= keyword for details.

This feature only works for the first two hours after an app has been created: after that the app plays normally.

sounds

If you prefer to supply your own sound files instead of having speech generated for you:

  1. Create a folder in your repository called sounds/.
  2. Record and edit the sound files you wish to use in mp3 format, perhaps using: Easy voice recorder or: Audacity.
  3. Upload the sound files to the sounds/ folder in the your GitHub repository.
  4. Code the names of the sound files as the value of this keyword. The names should not contain spaces or commas. The names should be separated by spaces and/or commas.

Alternatively specify urls starting with http(s): locating an mp3 file to use as the sounds for this photo.

The recorded sound will then be played instead of any generated speech.

See also fact.sounds= keyword

title

title

The title for this photo. Take care not to use a question! The title of the photo will be used as both a question and an answer by the app and so if you add words such "Is this" or punctuation such as "?" to make it a question then the usage as a question might work, but the usage as an answer will not.

The title should be as short as is feasible. If the title contains redundant text which is repeated from photo to photo, then the app becomes an app for teaching the student the redundant text rather than the original material as it is the redundant text that the student will hear the most and thus learn the first.

This gives rise to the most important rule of educational game development: everything must change except the truth.

Use the photo.say= keyword if you wish to say something other than the title when describing the photo.

url

aFewChars or url

If the URL starts with https?:// then this is the location of the image on the World Wide Web from whence it will be copied. For example:

  https://upload.wikimedia.org/wikipedia/en/7/7d/Bliss.png

If the URL starts with github:// then this is the location of the image in another GitHub repository: code the user name, '/', repository name, '/', followed by the path in the repository to the image file. For example:

  github://philiprbrenan/vocabulary-1/images/Ant.jpg

Otherwise it is the name of a file in the images folder in the GitHub repository for this app. For example:

  Ant.jpg

Photos should be high resolution: crop the photo to centre the object of interest and remove extraneous details.

The app will move long thin or tall narrow photos around on the screen so that the student can see all of their contents. This leads to a motion effect which is desirable for apps about skyscrapers, airplanes, bridges, boats, trees etc. as it adds realism. To reduce this effect: crop the photos into squares, to accentuate it: stick photos together in a long line.

The student will be able to pan and zoom the photos in the app to see fine details so it is worth using high resolution photos to facilitate this capability. Conversely, low resolution photos will pixellate if the student zooms them.

If you include identifiable people in your photos in an app you should get signed model releases from the persons involved.

wiki

The URL of the Wikipedia article describing the concept this photo illustrates

fact

A fact about one or more of the photos that the student can be tested on

aspect

The aspect of the photo under consideration which allows facts from different photos to be matched during the wrong/right response display.

The aspect of each fact is also used in race mode to test the student once the student has correctly recognized several photos and facts with the same aspect. Thus if you were writing an app about horses, and an aspect of each horse was its country of origin, then: once the student demonstrates that they know the country of origin for several horses, one or more races will occur in which the student is tested on just the country of origin for each horse.

name

nameA short name for this fact which will be matched against photo names as described in matching names

remark

An explanation of why this fact cannot be used as a question if, in fact, this fact cannot be used as a question

say

The actual words that should be said by AWS Polly if this is different from the fact.title= keyword.

sounds

If you prefer to supply your own sound files then use this keyword to specify the location of the mp3 files to use instead of generated speech. See photo.sounds= keyword for full details.

title

titleThe text of this fact

wiki

The URL of the Wikipedia article about this fact

 

Compressed Syntax

Normally you should place the command name alone on the first line and then follow the command with one or more keyword = value pairs on subsequent lines. To save space, the command and the name and title keywords can be combined into one line. So the code:

  photo
    name  = white.cliffs
    title = The "White Cliffs of Dover" from an arriving ferry

can be combined to save space by writing it as:

  photo white.cliffs = The "White Cliffs of Dover" from an arriving ferry

 

Matching names

An app is built from photos and facts. Each corresponding photo and each fact should have a name = value keyword/value pair to specify a label and description for the photo or fact. The names are matched so that in the following:

  photo sky       = The sky above us
  photo sky.blue  = Blue skies over the sea
  photo sky.red   = Sunset

  fact sky      = The heavens above us
  fact sky.blue = Lots of sun shine soon
  fact sky.grey = Rain will fall soon

the following matches will be made:

CommandNameApplies to
fact sky All three photos.
fact sky.blue The photos "The sky above us", "Blue skies over the sea" but not "Sunset".
fact sky.grey None of the photos.
photosky All three facts.

The student will be tested on the word sky and the phrase "The sky above us" using all three photos.

However, with the above source code the student will never see "Rain will fall soon" as the fact named sky.grey does not match the name of any photo. Adding a photo with a name, for example, sky.grey.rain would bring this fact into play by matching the name of the photo with the fact's name of sky.grey.

 

 

Distribution

Each app encourages its students to send a link for the app to their friends so that they can play the app too. To reach the first set of students who can seed this organic growth for you, please consider publishing your app on one of the following public platforms:

 

Upload a movie of the app to YouTube

Create a movie of your new app with a voice over explaining why you think people might like to play your app and publish it on YouTube.

In the description of your movie include a link to the app on AppaApps so that students can download and play your app immediately.

 

Put a link to your app on your web site

Place a description of your app on your web site and provide a link to AppaApps so that the student can download and play your app immediately.

 

Upload your app to Amazon App Store

Upload your app to: Amazon App Store.

 

Upload to Google Play

Your new app will work on Google Play.

Disadvantages
  1. One time fee of $25 to create a Google Play Account
  2. Your app will be lost amongst the millions of apps published on Google Play.
  3. Uploading to Google Play currently involves accepting the possibility of receiving a multitude of email messages that you might not wish to have to deal with.

 

 

Notifications and Rewards

Each app prompts its user, on occasion, to send a copy of the app to their friends to encourage the organic growth of the app's user base through student to student distribution:

Such distribution is very valuable to an app author because it results in their app being more widely seen. Indeed, wide distribution is crucial if the author's goal is to use the app to locate people to fill a job or apprenticeship with people who have a genuine interest in the author's subject matter of as indicated by their willingness to play an app about it.

Imagine then for a moment that Anna has created an app that has been distributed as follows until it eventually reached Dora who has learned to play the app so well that the app prompts Dora to contact Anna to see if she can have a place on Anna's apprentice training scheme.

  Anna     - the app author sends her app to:
  Beatrice - an early adopter, who recommends it to:
  Cuthbert - who knows just the person to send it to:
  Dora     - who learns so much that the app prompts her to contact Anna

Distribution of this nature is so valuable that Anna might wish to contact Beatrice and Cuthbert to discuss how they can help distribute Anna's app further.

However, to fully comply with: European Union: General Data Protection Regulation AppaApps does not record any information that might allow AppaApps to personally identify the people who have received and distributed copies of an app. Nor does AppaApps store their IP or MAC address, Google advertising ID or the phone's CPU id.

AppaApps does store a large, unique, randonly chosen number in each app downloaded. Every time Beatrice makes a recommendation to a potential student like Cuthbert, an encoded version of this number is included in the recommendation. When Cuthbert downloads a copy of the recommended app from AppaApps, AppaApps creates a new number for Cuthbert's app and records the connection between the app given to Beatrice and the app given to Cuthbert. The process is repeated when Cuthbert recommends the app to Dora. At no point does AppaApps store any information that might enable any-one with access to AppaApps to identify who in fact Beatrice, Cuthbert or Dora are. All that is recorded is that copies of the apps were distributed in a particular sequence.

Each time such a recommendation results in a new download, the author will receive a notification that this has happened via a GitHub issue. The successful recommendation will also be recorded in the app's GitHub repository in a file in the downloads folder as in:

The From: number is the encoded version of the unique number in Beatrice's copy of the app. The To Number is likewise the encoded version of the unique number placed in Cuthbert's copy of the app.

Now imagine that Dora learns to play Anna's app so well that the she reaches a level of play, predetermined by Anna, at which point the app invites Dora to contact Anna to inquire about a place on Anna's training scheme. If Dora accepts the invitation she sends an email to Anna which includes the encoded version of the secret number in her copy of the app.

Anna is now particulary interested in how her app got to Dora because she would like to encourage the people who played a part in this chain of events to increase their efforts to see if more candidates such as Dora can be found. However, no-one knows the identities of these people! The only information that Anna has is the encoded forms of the unique secret numbers in each person's copy of the app.

If Anna places an invitation in a file in the rewards folder of the repository containing her app using the From identity received from Dora:

then the next time that Cuthbert start Anna's app, the app will check for messages addressed to the unique secret number in his copy of the app. If Anna's message addresses that number then the app will show the message to Cuthbert.

Cuthbert can then send this email to the app author if he wishes:

Cuthbert's email will contain a copy of the secret number contained in his copy of Anna's app.

When Anna receives Cuthbert's email she can use the secret number to verify that Cuthbert's copy of the app did indeeed recommend the app to Dora.

Conversely, if Eggbert gets in contact claiming that he is the person who distributed Anna's app so effectively, he will be unable to produce a matching secret number so his claim to fame can be safely dismissed.

To achieve this result each copy of an app contains a unique secret number known only to AppaApps and to the person downloading and installing the app. When they in turn send a recommendation email to another potential student, that email contains the Sha-256 encoding of the unique secret number. This provides just enough information to allow Anna to invite only those people who contributed to getting the app to Dora and to validate their contribution should any of them choose to get in contact.

 

 

Zoom and Pan

Students will be able to zoom and pan all the images in your app. This makes it worthwhile to use high resolution photos in your app, especially if they contain small details that the student can examine by zooming and panning. You can make your app more interesting by posing questions that will require the student to examine the photos carefully in detail to find the photos that answer your questions.

To zoom any image: touch the image on the screen so that the action compass appears. Swipe West to the word Move to place the app in zoom and pan mode. Touching the screen again, without moving, will cause the image to be zoomed around the touched point. Moving your finger around on the screen will cause the photo to pan - to move - on the screen without being zoomed further so that areas hidden by the zoom can be brought into view and examined in more detail. Moving your finger and then stopping while still touching the screen causes the image to dezoom, that is to shrink, around the touch point. To resume normal play: tap the screen quickly.

 

 

Useful links

App command keywords app
Example Apps example apps
Fact command keywords fact
GitHub Notifications pageGitHub Notifications
GitHub Tokens page GitHub Tokens
Help philiprbrenan@gmail.com
Photo command keywords photo
Sample app on Google PlayCars, Cranes, Trucks, Trains
Sha 256 Duck Duck Go
Source for sample app Cars, Cranes, Trucks, Trains
Speakers available Speakers available on Amazon Web Services
Text Editor Geany

 

 

Processing Summary

Setting up a GitHub account and creating a first repository is a complicated process. Here is a summary of the main interactions between the author and AppaApps:

StepAuthorAppaApps
1Sets up a GitHub account.
2Creates a personal access token and sends it by email to: philiprbrenan@gmail.com
3Installs token as described in savePersonalAccessTokens.pl
4Sets up notifications
5Creates a repository
6Invites AppaApps to collaborate on their repository and waits for AppaApps to notify them that their repository has been set up.
7Accepts the author's invitation and starts watching the repository.
8Creates the web hook (aWebHook) and the images/ folder for the author which sends a notification to the author confirming this has been done. Follow up with an email or skype to confirm in case of GitHub email problems.
9Receives confirmation that the web hook has been created and starts to create the app.
10Adds photos to the images/ folder
11Checks that sourceFile.sample.txt is being updated.
12Writes sourceFile.txt
13Watches the first app generation either via GitHub issues or email copied to AppaApps
14Downloads new app to phone and tests