FACULDADE DE E NGENHARIA DA U NIVERSIDADE DO P ORTO

Technical Report

Invicta Uncloaked
Multimedia Laboratories, 2014

C ONTENTS
1 Introduction

2 System Architecture

3 Technologies & Platforms

3.1 Most Innovative Technology - Interaction with Facebook Fictional Characters
3.1.1 Short Description of the Facebooks API . . . . . . . . . . . . . . . . . . .
3.2 Android Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.1 Application Graphical User Interface . . . . . . . . . . . . . . . . . . . .
3.3 QR Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.4 Global Positioning System - GPS . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.5 Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.5.1 Server - Android Application Interface . . . . . . . . . . . . . . . . . . .
3.6 Servers Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.6.1 Database structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.7 Fictional Website . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.8 Videos with parts of the story . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.9 Promotional Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.9.1 Promotional Website . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.9.2 Promotional Facebook . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.9.3 Youtube Teaser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

4
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

4
5
5
6
6
7
7
7
8
9
9
9
9
9
10
10

4 Use Cases

10

5 Prototype

11

6 Conclusion

12

1 I NTRODUCTION
This document refers to a project currently being developed in the course Multimedia Labs
with the name of Invicta Uncloaked. The latter consists of a multi-platform experience that is
going to make the users go around the city of Porto, allowing them to discover it while they
engage in a thrilling puzzle solving game.
Herein, the technical part of this project, namely, all its platforms and how they interact
with each other, is presented. The goal is to offer a great insight on the projects technical
implementation and to expose its most challenging technical issues.
Therefore, this document will later be used as the main reference for the implementation
of the project.

2 S YSTEM A RCHITECTURE
On its essence, the architecture will have Client-Server scheme, where the Client is the Android
application and the Server a Java Application running in a backend PC. Of course there are
other relevent aspects, such as the use of the Facebook API or the Database access that will be
described further in this report.

3 T ECHNOLOGIES & P LATFORMS

In this project everything the user needs to be part of the challenge, travelling around the
city of Porto and following the clues, is a smartphone. This simple device will be responsible
to track each user, i.e getting information about its location so it is possible to conclude
about the current stage of the game and trigger the next action, provide the necessary clues
using different kinds of platforms and joining different users so they can interact by providing
information about the proximity of each other.

3.1 M OST I NNOVATIVE T ECHNOLOGY - I NTERACTION WITH FACEBOOK F ICTIONAL

C HARACTERS
The point through which this work promises to push forward the boundaries of the user
experience, is the existence of fictional Facebook accounts associated with game characters
that will interact with the user as if they were real people.
This interaction will take two main forms:
Facebook posts in a secret group with real users and fictional characters - In this
group, the fictional characters will make posts according to the progress of each user in
the game, providing the users with additional clues that will help them progressing in
the game.
Facebook private messages sent to individual users - This messages will be sent by a
fictional character that will be a friend of the users character and that will help him
progressing in the game by sending him messages according to his actions.
Although the two might seem as if the have similar functions in the game, in fact this is not
quite true. Despite the fact the both are user-specific, from the users point of view, the first
will seem a general post that is not addressed to the user, whereas the second will make the
user feel that is being addressed directly. This makes the experience feel much more real and
that is why both forms of communication will be part of the project.
Thus, Facebook will be the basis of the system to user communication.
In order to implement this feature one must use create a Facebook Application:
Definition 1. Facebook Application
A Facebook application is not a specific code that is integrated in some sort of environment
or an application database. It is rather any kind of process that uses a uniquely identifiable key
(also called Token) and interacts with the Facebook Graph API through HTTP requests. Thus, all
the processes, being they written in whatever language or being integrated in whatever platform
are considered to be the same Facebook application as long as they use the same key.
Example: A Java application running in a server and an Android Application running in
a smartphone are considered to be the same Facebook application as long as they use the same
key.
The Facebook Graph API is an interface based roughly upon the exchange of HTTP
requests and responses that allows applications to perform operations on behalf of the users,

among other features. On top of this API, Facebook offers some SDKs that provide developers
with high level interface that these can use in their applications, but there is none aiming for
Java development.
Since it was decided that it would be a backend server to perform such operations
(obviously in response to each users actions) and it would be developed in Java (explanation
further in this report), there was the need to find an open-source code suitable for this purpose.
Thus, after a good amount of research and development of test implementations, it was
decided that the chosen one would be RestFB, due to its simplicity and capability of addressing
this specific issue.
In order for the messages posted by an application to be seen by other users, this
application must have been approved by the Facebooks team. This implies that the app must
meet several requirements like being harmless (in their standards) and having a proper logo,
even if the application is not going to be available for other users, as it happens in this case.
Of course, the users would have to be automatically invited to the mentioned Facebook
page and this would only be possible if there was another Facebook application just for this
purpose. Therefore, besides the application that allows the fictional users to make posts, there
would have to be another application, just with the privileges to invite real users to the group.
Zs

Thus, the Android application (see further on this report) would have to use the FacebookA
Android SDK, in order to allow the user to login and ask him for the privileges needed to invite
him to the group.
3.1.1 S HORT D ESCRIPTION OF THE FACEBOOK S API
In order for an application to interact with facebooks data, it must have an Access Token.
There are several kinds of Tokens, each one with different privileges related to what it allows
the application to do, and they can last up to two months before needing to be renovated. For
the purpose of this project, i.e. in order for an application to post messages on behalf of the
user, it must have an User Access Token.
The way through which these are generated is a bit complex (at least regarding the low
level API), however, since in this project it is needed only one Token for each of the fictional
characters, they can be "manually" requested using an application testing platform called the
Facebook Graph API Explorer every two months.
Once the application has these tokens, it must provide them to the Facebook API in
each HTTP request in order to perform the required operations.

3.2 A NDROID A PPLICATION

As the used device is a smartphone, it is necessary to develop an application in an integrated
development environment (IDE) for the Android platform. The application is developed using
the API level 18 (Android version 4.3) and provides the main interface between the user and
the system as:
Login with the users Facebook account, in order for him to be invited to the Tuna Group;
Runs in background a GPS service to track the user and send information to the server;

 Runs a QR Code activity, which is also responsible to send the current stage of the game
to the server;
Therefore the application constantly communicates with the server in order to inform it
about the user stage in the game and will be the basis of the user to server communication.
Definition 2. Activity
In Android programming context, an activity is an application component that provides
a graphical interface to the user (screen), in which the user can interact in many ways with
the phone. In the mentioned examples these ways are typing his personal data, reading the
information and taking a photo.
Therefore, an application is a set of connected activities and each activity contains also
the logic of the interfaces.
3.2.1 A PPLICATION G RAPHICAL U SER I NTERFACE
The graphical user interfaces of the application will consist of the following windows/activities:
1. Login activity as the first window with the fields email and password of the Facebook
account that the user should fill in;
2. Activity with information about:
Which clues the user has already found out, so he can better keep track of the story;
Guidelines/instructions of how to use the interface;
Button that the user should press everytime he wants to use the QR Code activity;
Button to Stop/Resume the experience;
3. QR Code activity, which consists, from the user point of view, of a camera and a button
that the user should press to take a picture to the QR Code. When finished the task, this
activity should return to the previously described activity.

3.3 QR C ODES
A QR Code consists of black modules arranged in a square grid on a white background forming
a pattern which can represent a code. The latter can contain a website URL, leading to it
directly, a text, allowing to see it automatically, or can be also be used to store bank account
or credit card information. A QR Code can also contain information such as phone numbers,
email addresses or other contact info.
A QR Code is read by an imaging device such as a camera, and thus smartphones are
typically used as a QR Code scanner, displaying the code and converting it to some useful
form. To do so, it is necessary to access the QR Code application in the smartphone and simply
point the camera to it.
Due to its user-friendliness and fast access, joining the fact that it arouses curiosity as it
has a imperceptible appearance, this technology was chosen as a way to provide clues and
also to trigger warnings inside the all project application reporting the actual stage of the game

in which each user is. This way it is possible to track what each user has already found out and
thus the QR Code acts as a checkpoint, allowing the system to trigger other actions.
From the user point of view, the QR Codes will trigger game actions such as playing a
video to the user presenting scenarios with clues.
In what regards the implementation of this technology, this solution would use an
existing android QR Code application. Thus, the projects application would implement a code
in one of its activities in the background to call the QR Code application, which would display
the video and return when finished its task.

3.4 G LOBAL P OSITIONING S YSTEM - GPS

The GPS is implemented in the projects application as an Android service, so it can run even
if the user switches the the applications window (activity). This service is responsible for
constantly providing the users location so it can be sent to the server.
The GPS service is implemented using the Android location service, which determines
the location using satellites instead of a network provider, which in turn, determines location
based on availability of cell tower and WiFi access points.

3.5 S ERVER
The server is the main module of the system, were all the information is gathered and processed. It consists of a Java application, due to the simplicity and predefined libraries of this
language which are adequate to the goals of this project. Its main functionalities are:
Receiving the data sent by the users (Android applications), including their positions
and current states in the game and keep it updated in a database;
Checking whether two users are near each other;
Checking whether a user is near a QR code spot;
Interact with the Facebook API in order to make posts/send messages on behalf of the
fictonal characters, and always in response to the users positions, current state in the
game and proximity to other users;
3.5.1 S ERVER - A NDROID A PPLICATION I NTERFACE
The Android application and the server will be connected through sockets, as usual, in a
request-response scheme. Since the communication will be bidirectional, i.e., since there will
be requests made by the server as well as requests made by the application, it is a good practice
to use two sockets, on for the servers requests and applications responses and vice-versa.
In order to ease the process of separating consecutive requests or responses in the same
socket, there will be used ObjectInputStreams and ObjectOuputStream. These are classes that
are constructed on top of a stream (in this case a socket stream) and that allow to send objects
that are individually read on the other end of the communication. The objects sent will be
called request and responses and will have the following declaration:

public c l a s s AppMessage implements S e r i a l i z a b l e {

public
public
public
public
public

byte messageType ;
S t r i n g userID ;
double l a t i t u d e ;
double longitude ;
byte gameStage ;

// Defines type of the message

//Facebook s email of the user sending the message
// Latitude of the user s current location
// Longitude of the user s current location
// User s current stage of the game

}
public c l a s s ServerMessage implements S e r i a l i z a b l e {
public byte messageType ;
// Defines type of the message
public S t r i n g nearbyUserID ; // User ID of a user that i s nearby (when
// applicable )
}

T YPES OF A PP M ESSAGES
Message 1 - Just an update on the users position - relevant fields: messageType, latitude,
longitude;
Message 2 - Change game stage - relevant fields: messageType, gameStage;
Message 3 - Resume Game - relevant fields: messageType;
Message 4 - Pause Game - relevant fields: messageType;
Importante note: This list might be changed further in the development of the project because
it is to soon to tell if there will not be needed more types of messages.
T YPES OF S ERVER M ESSAGES
Message 1 - Notification of a nearby player - relevant fields: messageType, nearbyUserID;
Importante note: This list might be changed further in the development of the project because
it is to soon to tell if there will not be needed more types of messages.

3.6 S ERVER S D ATABASE

Since, as mentioned previously, in this project there will be several users playing concurrently
and there is the need to keep the information regarding each one, i.e., its identity, its position
and its state in the game, among others, it is of absolute importance to use a database for this
purpose. The latter will be developed in SQL because this language is suitable to the projects
demands, which are:

 Moderate database access;

Database operations integration with Java (package java.sql);
Automatic concurrency handling;
Relational database due to its simplicity since performance is not a key issue;
3.6.1 D ATABASE STRUCTURE
From what was already described, it is clear that there is only the need for one table in the
database and it will be implemented as follows:
CREATE TABLE Users (
email varchar ( 3 2 ) PRIMARY KEY ,
/ * User email from Facebook account * /
game_stage t i n y i n t ,
/ * The current stage in the game of the user * /
p o s i t i o n _ l a t double ,
/ * The current l a t i t u d e coordinate of the user * /
position_long double , / * The current longitude coordinate of the user * /
play boolean
/ * True i f the user i s playing * /
);

3.7 F ICTIONAL W EBSITE

This website is a platform that is used to provide the user a more realistic scenario, since it will
be designed to represent the website of a Porto wine company. The user will use this website
to find more clues about the mystery, namely the wine company address, where he should go.
It will be stored in the server.
Since this website will have a simple structure, it will be developed using online tools
that generate HTML/CSS code for simplicity purposes.

3.8 V IDEOS WITH PARTS OF THE STORY

One of the platforms used for the purpose of storytelling will consist of several videos with
parts of the story that will be presented to the user every time he finds a new QR code block.
In order for these videos to be easily accessible from the Android application and at
the same time inaccessible for normal internet users (to keep the secrecy of the videos), they
will be stored in Google Drive. Thus, when a user reads a QR code, the latter will give the
application a link without which it would be impossible to find the video.

3.9 P ROMOTIONAL P LATFORMS

3.9.1 P ROMOTIONAL W EBSITE
This website will serve as a promotional medium that will present the project to potential users
from a marketing point of view and hopefully make them curious and interested in experience.
It will also be stored in the server.

Since this website will have a simple structure, it will be developed using online tools
that generate HTML/CSS code for simplicity purposes.
3.9.2 P ROMOTIONAL FACEBOOK
With a function similar to that of the Promotional Website, but integrated in this social network
due to its ability to spread what people like to their friends.
3.9.3 Y OUTUBE T EASER
Similarly with the two already mentioned promotional platforms, the Youtube platform will
have a video in order to captivate people to join the game. The aim is to give a glimpse of what
the user will experience and hopefully let him curious and excited to be part of the challenge.

4 U SE C ASES
The use case diagram is described as follows:

10

5 P ROTOTYPE
The all project was exposed in this report, howeve, the lack of time to implement it all aroused
the need to choose only the technologies considered to be the most challenging from a
technical point of view and most differentiating from the user experience point of view.
As mentioned before, the most innovative part is the interaction with Facebook fictional
characters. Since the Facebook developers section is much more aimed to the SDKs mentioned
in this report, it does not provide a clear documentation (like a tutorial) regarding how the low
level API works, that would be easy for an outsider to understand. On the other hand, it was
not easy to find an open-source library due to the lack of documentation that makes it very
difficult to assess what each library can do and how to use it.
Thus, since the Facebook interaction is by itself a complicated issue for the reasons
already exposed above, it was chosen to implement this technology.
For this purpose there is the need to implement also the GPS service running in the
android application, since the automatic posts and messages depend on the users position.
In short, the prototype will contain the demonstration of:
Automatic posts according to the users location;
GPS tracking;
Application prototype (short version).

11

6 C ONCLUSION
In this report it was given a clear insight on the complete system which is the technical
foundation of the project. While this was done from a high level point of view, no important
technical details were left out of this document. Therefore, the level of definition that this
report provides, allows the projects implementation to have a clear path to follow, that is
however, opened to new additions or small changes.

12