Create an Interactive Book Reader

Check out the demonstration HERE

And find the code at GitHub.

Table of Content

1. Scope

1.1 What does it do?

1.2 How does it work?

2. The Recipe

2.1 Ingredients

2.2 Preparation

2.2.1 Setting up the web host
2.2.2 Setting up the Conducttr project

3. Method

3.1  Edit and upload the code snippets

3.2  Implement the logic in your Conducttr project

3.2.1  Create the setup calls to configure the book player

3.2.2  Determine and implements the interaction between the book and the audience


1  Scope

This document describes how to create an personalized interactive book that can interact with the Audience. The Audience can also control the 


1.1  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 the reader unlocks the content 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.


1.2  How does it work?

You’ll need a web server to host three code snippets (“index.html”, “book.php” 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 “book.php” and "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.html” hosted on your server) they 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 form is submitted the web page redirects to the book page (the file “book.php”). As the audience reads, the web sends triggers to your Conducttr project to tell it how far along the book it is. It doesn’t do this automatically – you must identify which pages and configure your book reader (explain in point 3.2.2). 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 unlocks some other pages (the file “api.php”)
  • 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.


2  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


2.1  Ingredients

You will need:

I.     a web host
II.    a Conducttr project
III.   a book (doc, pdf or similar) hosted on ISSUU
IV.   Twilio account for mobile calls & SMS
V.    Basic text-ending software to edit the code such as Notepad

Your web host will need:

  • PHP 5
  • MySQ
  • Code snippets from Conducttr (You can find all the files here):

              - The "index.html" code snippet

              - The “book.php” code snippet

              - The “api.php” code snippet.

              - The OAuth library 


2.2  Preparation

To prepare, you’ll need to:

  • Setup your web host
  • Setup your Conducttr project


2.2.1  Setting up the web host

I.   Register a domain name (e.g.  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:


*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 

2.2.2  Setting up the Conducttr project

I.  Create a Conducttr project

Create the basic logic

II.  Create a new API entry inside Conducttr 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 /book.php )



3   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 

3.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:


*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”.

Copy the code and open file index.html paste the code into it, at the beginning of the file as show in the image below:


Append the Conducttr signup widget inside it.  Upload it 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 ”book.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 .


3.2  Implement the logic in your Conducttr project

Once we have upload everything to our web host, we will configure the book reader size, the page triggers and the deafault locked content 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 triggers and actions to determine the interaction


3.2.1   Create the setup calls to configure the book reader

We are going to create five API calls that will configure the book reader. 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 Table.

The calls will be:

  • Initialize: creates the tables 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 reader:

  • 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 opened 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,1], [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 READER 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

Readersize: http://MYURL/api.php?action=get_reader_size



3.2.2  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. We can have two kinds of interaction: from the Audience to book and from the Book towards the Audience.


I. Interaction from the book towards the Audience: 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 to the Audience members who reach a certain page, in our example we add them to a Group to track how many people unlocked the content,


II. Interaction from the Audience towards the book: The audience can interact with the book in different ways. By default will ask the Audience their phone so the easiest way is to use SMS or Phone calls.

The Audience can send a SMS to unlock contents in the book or turn the page. In order to achieve this we just need to:

- Create SMS or Phone Call triggers in Conducttr with a matchphrase.

Create the API Calls to lock or unlock pages

Method: POST

Format: JSON

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


{"book_journey": []}



- Create the API Calls to turn the page.

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:


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 

- Create as many Logic/Content action as you want. E.G You can send a welcome SMS or phone calls to the Audience members who reach a certain page, or reset their attributes.


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