Follow

Create an Interactive Book controlled with NFC tags

Find the code at GitHub.

Table of Contents

1  Scope

2  What does it do?       

2.1  How does it work?

3  The Recipe    

3.1  Ingredients               

3.2  Preparation              

3.2.1  Setting up the web host 

3.2.2  Setting up the Conducttr project  

4  Method         

4.1 Edit and upload the code snippets  

4.2  Implement the logic in your Conducttr project        

4.2.1  Create the setup calls to configure the book reader         

4.2.2  Create the setup calls to synchronize the web and the app           

4.2.3  Create the triggers and actions to determine the interaction       

4.3  Update the app code 

          

1  Scope

This document describes how to create a personalized interactive book capable of interact with the Audience that can be controlled using NFC tags.

 

2  What does it do?

Every audience member can control their personalized path through the book on triggers they send from some other device. In the example below, some of the book’s content is locked from the beginning and the reader unlocks it by touching a NFC tag with her phone


The book is hosted on ISSUU and run on your webpage inside a Conducttr code snippet that listens for and sends instructions.

 

2.1  How does it work?

You’ll need a web server to host three code snippets (“index.php”, “login.html” and “api.php”), the Oauth library and a MySQL database.

The file “api.php” need to be modified adding the details of your database and details from your Conducttr project before being uploaded to your web host.

The three files and the Oauth library must be uploaded to the same folder in your Web host, otherwise you will need to change the path to “api.php” in “index.php” and the "login.html", and the path to the Oauth Library in the “api.php.

The MySQL database remembers which audience member is reading the book and their journey. This allows many people to be active at the same time yet each have unlocked a different content and have a personalized experience.

The server is able to send triggers to Conducttr based on the actual page (configured by you) and is able to turn to a new page or lock/unlock content based on API calls from Conducttr.

The figure above shows how it all fits together:

  • The audience visits a web page (the file “index.php” hosted on your server) and can read “limited” version of the book . If they want to unlock the rest of the book they need to click in the displayed link.
  • In this new page (the file “login.html”) the audience can choose the way to interact with the book, using an Android App which will read NFC cards or via SMS.
    • If they choose to use the Android App, the page will show a code they will have to enter in the app. Conducttr will synchronize the app and the web, so they "know" who  the audience member is.
    • If they choose to not use the App, the audience will have to enter some identification, such as a mobile number, into a modified Conducttr solo sign-up form. This information is sent to Conducttr and it’s also registered in the local database.
  • When the code or the form are submitted the web page redirects back to the book page (the file “index.php”). As the audience reads, the web sends triggers to your Conducttr project to tell it how far along the book ithey are. It doesn’t do this continually – you must identify which pages and configure your book reader (explain in point 4.2.3). You can use the page triggers to send content personalized to the audience member reading the book.
  • The audience is also able to send instructions to the book. All audience interaction goes to Conducttr and then Conducttr makes an API Call to the server. The server looks up the book details in the database and then turns the page or locks/unlocks some other pages (the file “api.php”)
    • The smartphone app will read NFC tags and send triggers to your Conducttr project, telling which tag the audience has read and triggering the events you have defined.
  • As the author, you will configure a default book journey (which parts are locked/unlocked from the beginning), the book size and the page triggers all inside Conducttr. Even if you need someone with more web development experience to set up the website, once that’s done you can fine tune and change the storytelling aspects without further coding.

 

3  The Recipe

This recipe has the following sections:

  • Ingredients - what you need to complete this project
  • Preparation - how to prepare
  • Method - step-by-step implementation guide

 

3.1  Ingredients

You will need:

I.     a web host

II.    a Conducttr project

III.   Code snippets from Conducttr (You can find all the files here):

IV.   a book (doc, pdf or similar) hosted on ISSUU

V.    Twilio account for mobile calls & SMS

VI.   Basic text-ending software to edit the code such as Notepad

VII.  Eclipse to edit the code app.

        - Eclipse & Android SDK bundle: http://developer.android.com/sdk/index.html
        - Eclipse: http://www.eclipse.org/downloads/

VIII. A set of NFC tags.

IX.   An Android smartphone with NFC capabilities and Android 2.3.3 or superior

 

Your web host will need:

  • PHP 5
  • MySQ

 

3.2  Preparation

To prepare, you’ll need to:

  • Setup your web host
  • Setup your Conducttr project

 

3.2.1  Setting up the web host

I.   Register a domain name (e.g. http://ww.zenfilms.com).  In this document will be using MYURL to indicate where you should replace with your domain name


II.  Ensure that your server runs PHP release 5 or higher. Our code will not work with PHP 4

III. Create a new MySQL Database on your web server. In most hosts this can be done in the administration panel or via command line. Also the “api.php” file provides a method to create the database that can be called writing this URL in your browser:

                                    http://MYURL/api.php?action=create_db

*Only some hostings allows this, you must consult first, and edit and update the file to your web host.

 

Below is an example of creating the database in GoDaddy:

  1. In the Databasessection of the Hosting Control Panel, click the icon corresponding to the database you want to create.
  2. Click Add.
  3. Complete the fields. To allow direct access, click Additional Options.
  4. Verify the settings and click OK

 

3.2.2  Setting up the Conducttr project

I.  Create a Conducttr project

Create the basic logic

II.  Create a new API entry inside Conducttr's API panel called “Website”

III. Create a new Solo Signup widget to collect the audience phone, with the Success URL pointing to the book page ( http:// MYURL /index.php )

 IV. Create a new Audience Attribute called “unique_code” of type Single-line text

 

4   Method

Now you have all the ingredients and you’ve followed the preparation, you’re now ready to configure the project. The steps are:

  • Edit and upload the code snippets to the web host
  • Implement the logic in your Conducttr project
  • Update the app code snippet with details from your project

 

4.1  Edit and upload the code snippets

First we need to edit the code snippets to add your database details and your Conducttr project. This will make the code snippets know which database and project we are using.

I.  Update the “api.php” code snippet with details from your project. When you open the code snippet, the area that you edit is between two comment lines. The start of the editable area says “Edit the information below” – as shown in the image.

You need to update the following information:

  • CONDUCTTR CONSUMER KEY  & CONSUMER  SECRET – you’ll find this in the Authentication section of the API pop-up

  • CONDUCTTR PROJECT ID – this is found in the top header bar

  • MYSQL HOST, DBNAME , USER and PASSWORD – you can check this information in your web hosting control panel. Below there’s an example of this info in godaddy.

  • ROOT MYSQL HOST, USER and PASSWORD (OPTIONAL) – you can check this information in your web hosting control panel. This information it’s only required to create the database calling the API:

                                               http://MYURL/api.php?action=create_db

*Only some hostings allows this, you must consult first.

When you’ve done all the changes upload the file to your web host.

 

II. Generate the HTML code of your Conducttr Signup Widget, clicking “Generate HTML”.

Open the file login.html, copy the Widget's code and  paste it between the comment lines shown in the image below:

 

Upload the file to your web host, in the same folder as your “api.php” file.

If you upload it to another folder you will need to update the file before uploading it.

 

 

III. Upload the ”index.php” code snippet to your web host, in the same folder as your “api.php” file.

If you upload it to another folder you will need to update the file before uploading it.

 

IV. Upload the Oauth library files to your server. Extract the “Oauth” folder in the same directory you have uploaded the “api.php” file. Otherwise you will need to update the “api.php” file .

 

4.2  Implement the logic in your Conducttr project

Once we have upload everything to our web host, we will configure the book, its size, the page triggers and the default book journey all inside Conducttr.   Also we will determine the interaction between the audience and the book creating triggers and actions.

  • Create the setup calls to configure the book reader.
  • Create the setup calls to synchonize the book reader and the mobile app.
  • Create the triggers and actions to determine the interaction

 

4.2.1   Create the setup calls to configure the book reader

We are going to create five API calls that will configure the book. We only need to call each method only once, unless we want to make any changes to the configuration of the reader, in that case we can make any of the API calls again just pressing the TEST button in Conducttr’s Content Details.

The calls will be:

  • Initialize: creates the tables (configuration and audience) in the database.
  • Set ISSUU Book: the ISSUU id of the book
  • Set Default Book_journey: defines which pages will be locked by default.
  • Set triggers: the list of pages cues.
  • Book reader size: determines the width and height of the reader

 

There are two basic components that define the behavior of the book:

  • BOOK_JOURNEY: list of pair of numbers that defines the interval of the locked pages.
  • TELL_CONDUCTTR_IM_HERE: array of pages cues. The first number indicates the page, and the second text is the API call’s matchphrase sent to Conducttr.

 

I. Initialize: This call will create two tables in your database and initialize them. You can do this creating an API call inside Conducttr or pasting the next URL in your browser

                             URL: http:// MYURL/api.php?action=initialize

 

II. Set ISSUU BOOK: first you need to upload a book to ISSUU and find its ID. After uploading, go to you publication and click “Share” and then “Embed”


You can find the ID at the bottom of the new pop-up

 

Create a new API Call with your book’s ISSUU id

 

Method: POST

Format: JSON

URL: http:// MYURL/api.php?action=set_issuu_book

DATA: { "issuu_book" : "12858737/8899511"}

 

 

III. Set Defaul Book Journey: – this tells the code which pages are locked from the beginning for all the audience. The image below shows an example. Pages 4, 5 and 6 are locked. And pages from 9 to 21 are locked.

 

Create a new API Call select Method: POST and Format: JSON

Method: POST

Format: JSON

URL: http:// MYURL/api.php?action=set_default_book_journey

DATA: {"book_journey" :  [ [3,7], [9,21]] }

 

 

IV. SET TRIGGERS – this is the array of page cues. The first number indicates the page in which the API call to Conducttr should be made and the second is the matchphrase’s text sent to Conducttr 

Method: POST

Format: JSON

URL: http:// MYURL/api.php?action=set_triggers

DATA: {“tell_conducttr_im_here" : [[1,"one"], [ 2, "two"], [3, "three"]]}

 

 

V. SET BOOK WIDTH AND HEIGHT – set the size of your book reader.

Method: POST

Format: JSON

URL: http:// MYURL/api.php?action=set_reader_size

DATA: {“reader_width" : 720, “reader_height” : 405 }

 

Click TEST from the Content Details to send each API Call

For each API Call, selecting the content in the Content Table and clicking the TEST button inside the Body tab. 

 

If the call is OK you should see an alert:

 

You can also check everything is fine, creating API calls in Conducttr or pasting the next URLs in your browser

ISSUU Book ID: http://MYURL/api.php?action=get_issuu_book

Book Journey: http://MYURL/api.php?action=get_book_journey

Triggers: http://MYURL/api.php?action=get_triggers

Reader size: http://MYURL/api.php?action=get_reader_size

 

4.2.3  Create the setup calls to synchronize mobile and web 

The next step it's implement the logic to link the mobile app with the website, this way they will be synchorinzed and "knowing" the audience using them.

The mobile app will call Conductttr when the Audience clicks the login button in the first screen, the code will register them in Conducttr and the Web Database.

 

I. API trigger : First you need to create an API Trigger with the matchphrase "registration"

 

 

II. API Call : Attached to the previous API trigger we need to create a new API Call content action.

Method: GET or POST

Format: HTML

URL: http://MYURL/api.php?action=create_user&audience_phone=|audience_phone|

 

The API trigger and the API Call should look like this in the Beat Sheet:

 

III. API Methods: The last step it's to create two API methods. In the API view. Click in your, previoulsy created, API entry "Website". In the pop-up go to the API Methods tab and create two new methods: "registration" and "code".

Both will have an API parameter "code" that maps to the Audience parameter "unique_code"

 - registration: This will be called by the app to register the Audience in Conducttr with their random Code.

- code: This will be called by the Website to check if the code it's the same in the App and in the web.

 

4.2.3  Create the triggers and actions to determine the interaction

Now it's the turn to determine and implement the interaction between the book and the audience. The interaction can go both ways: from the Audience to book and from the Book towards the Audience.

 

I. Interaction from the Audience towards the book: In our example the Audience can read an NFC tag with their phone or send a SMS to unlock contents in the book or turn the page. In order to achieve this we just need to:

- Create API triggers in Conducttr with the matchphrase we encodedinside the NFC tag (you can write texts in your NFC tags using an app like Tag Writer).

*We also created a SMS trigger with a matchword "card",to provide an alternative to those member of the Audience who don't have the app.

Create the API Calls to lock or unlock pages (for each Audience member)

Method: POST

Format: JSON

URL: http://MYURL/api.php?action=set_book_journey&audience_phone=|audience_phone|

Data:

{"book_journey": []}

 

 

- Create the API Calls to turn the page (for each Audience member)

Method: GET or POST

Format: HTML

URL: http://MYURL/api.php?action=set_nextpage&audience_phone=|audience_phone|&nextpage=8

 

This is how it can look in the Beat Sheet:

 

II. Interaction from the book towards the Audience: Also we can know which page the audience is reading and send them content or trigger other actions.

- Create API triggers in Conducttr that will fire when the book reader calls them.

You need to create  an API trigger for each page cue – like the one shown below ( check they are the same used before 4.2.1 - IV)

 

  - Create as many Logic/Content action as you want. You can send SMS or phone calls to the Audience members who reach a certain page, or add them to a group to track how many people unlocked the content,

 

III. Reset the Audience (OPTIONAL):  The book reader sends an API Call with the matchphrase "reset" every time an Audience member reloads the website or enters again. This is useful if in your project you use attributes to set them to their default values or not (depends on your project logic)

- API trigger: If you want use this feature you just need to create a new API trigger with the matchphrase "reset" and attach to it all the logic or content actions (E.G. a welcome messsage) do you want 

 

4.3  Update the app code

Import the LondonVoodo-app project into your workspace in Eclipse.

File -> Import -> Android -> Existing Code into Workspace

Then open  src->com.conducttr.londonvoodoo_dev-> Constants.java

The area that you have to edit is between two comment lines. The start of the editable area says “Edit the information below” – as shown in the image.

 

You need to update the following information:

  • CONDUCTTR CONSUMER KEY  & CONSUMER  SECRET – you’ll find this in the Authentication section of the API pop-up

 

  • CONDUCTTR PROJECT ID – this is found in the top header bar

 

 

After that you can build and export your NFC reader app.

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments