Follow

Communicator

Hotlinks:

Communicator message syntax is here

Communicator images file is here

Table of Contents

1 Scope

Conducttr Communicator is an open-source, customizable front-end web-app that gets Conducttr authors up and running faster.

Designed to run on mobile but capable of running on desktops too, this responsive web app offers all the convenience of a mobile app without the coding, the delays or the cost.

1.1 What does it do?

The Communicator will act as word warden, a private channel for your stories.  As an author you can deliver content to your audience, and make sure it doesn’t end in a Spam folder or ignored.

1.2 How does it work?

There are two ways to get the communicator:

  • Hosted version (CM.CR): If you have a Conducttr license, you can have your own Communicator hosted in our server. You will have your own domain YOUR-PROJECT.cm.cr. You can use the default styling or personalize it.
  • Stand-alone: pick the code and install it in your server. Use it out-of-the-box or customize the style and/or the way it works

 

The Communicator uses Message Feeds to display the content of your Story.

Either if you use our hosted version (CM.CR) or host the Communicator in your own Server or Web Hosting, the communicator will work in almost the same way. It will call Conducttr to get your audience Message feed and present them as content inside fake apps.

The benefit of the hosted version is that it is more responsive because of the closer integration between Conducttr and the Communicator server.

 

 

2 THE RECIPE

Each recipe has the following sections:

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

2.1 Ingredients

For the hosted version you will need:

  • A Conducttr license. 

2.2 Preparation

Before following the Method section, please do the following:

  • Create a Conducttr project using the Template "Communicator"
    • "Communicator - Basic": The basics you need to start. 
    • "Communicator - Full": A template with more methods and logic.
  • Create new API entry inside Conducttr (call it "Communicator")
    • If you are using the template enter in the Communicator API entry, go to the Authentication tab and reset your Consumer Key.
  • Request Access:

Submit a request to our Help system with the title “Access to Conducttr Communicator” and attach the following details:

    • PROJECT_ID: You can find at the top of Conducttr

 

Inside the API panel -> Authentication tab:

    • CONSUMER_KEY
    • CONSUMER_SECRET
    • ACCESS_TOKEN
    • ACCESS_TOKEN_SECRET

  • A unique name for your project, it will be used for the URL.

YOUR-PROJECT.cm.cr

Optional

  • If the project is going to work with badges (you don't to create all of them from the beginning) :

Create a Group, this will act as "Parent" group and all the badges will be inside it. Copy the group id in your access request.

Later on you just need to select this group as Parent when you create the Badges and they will be displayed in the Communicator.

2.3 Method

Once you have access to the Communicator, your project created using the "Communicator" template is ready to be used!

You can check it working in the url:

YOUR-PROJECT-ID.cm.cr or YOUR-PROJECT-UNIQUE-NAME.cm.cr

 

If you want a create the logic from scratch, or modify the existing logic, these are the steps to achieve it:

  • Create a Message Feed.
  • Create a Communicator Channel.
  • Create a Post to Communicator.
  • Create the API method

 

2.3.1 Create a Message Feed.

The Communicator can work in a Project or Audience level. You can use one, the other or both at the same time.

The content posted in a project level message feed will be seen by all the Audience, and if you choose the Audience level, each member of the audience will have a unique feed, that you could fill with different and customized content.

To create the Message Feed open the Attributes tab and select Entity Project or Audience and click the "+" icon and select the Message Feed type.

 

2.3.2 Create a Communicator Channel.

Go to the Characters tab, select the character you want to add a Communicator channel. Select the type of the Channel:

  • Msngr: a chat feed.
  • GoSocial:  a social network.
  • MicroBlog: a microblogging app.
  • Mail: a mail manager
  • Blog: a blogging client.
  • Media: A depositbox for important files (Files folder in the bottom menu)

And select where the messages will be posted to which message feed from the previously created.

 

2.3.3 Create a Post to Communicator

Once you have the Message Feed and the Communicator Channel, you can create as many Posts To Communicator as you want. 

You create a Post To Communicator just in the same way you create any other content in Conducttr (email, tweet, facebook post) 

Create a new content and select the Post To Communicator type. Once you are in the Content Details panel, go to the Header tab and select in the From drop-down list which character and channel is making the post.

Fill the Body using the correspondant format (Check: 3 Formatting the Content ) and save it.

The Posts to Communicator can be fired by any kind of trigger you want, by default the Communicator sends some API Calls to your project you can use to publish some content:

  • registration : An API Call sent from the Communicator when an audience member enters for the first time in the Communicator, you can use it to publish the first content and start the experience
  • login : An API Call sent from the Communicator every time an audience member enters the Communicator, you can use it to track their behaviour, increments their points or publish new content.
  • update_profile: An API Call sent from the Communicator every time an audience member updates their Communicator's profile, you can use it to track their behaviour, increments their points or publish new content.

 

2.3.4 Create the API method

  • get_communicator

Enter the API app entry and go to the Method tab. Create a method call "get_communicator" and add your message feeds as parameters (the name doesn't matter). Add all the message feeds you want to display in the communicator.

  • get_stats (Optional)

An optional method to display the Points and Progress of your audience in your Communicator.

Enter the API app entry and go to the Method tab. Create a method call "get_stats" and add three attributes:

    • points: Map to the Audience XP
    • max_points: Map it to an attribute that will act as the maximum ammount of points. You can create a Project attribute.
    • progress: Map to the Audience progress

2.4 Style Customization

Once you have access to the communicator, you can modify the default style and images of the communicator - found here - and send them back to us and we'll update your Communicator

You can customize:

  • Header image
  • Background image
  • Icons images
  • Characters profile images, [name of the character].png (E.G “robert.png”)
  • The style itself: communicator.css
  • The notifications sounds

 

3 Formatting the Content

Each Post to Communicator can contains as many messages as you want.  These messages can be pure text or embed an image, audio or video. You can also specify dates to make the content look more realistic.

In some apps (Msngr, GoSocial and Microblog) each message must be in a separate line and start with a character and a dot. This character defines the type of content (text, image, sound or video) after that you can write the name of the character between square brackets.

EG:

t. [John] Hi! how are you?

i. [John] Amazing check this pic:  http://an.cr/sa/yshkM

 

In other apps (Mail and Blog) each message is separated using the character name between brackers. Also you can embed images, sound or videos starting a new line with a character and a dot and the correspondant url:

EG:

[Javier] Welcome to the Newsletter

this is the body

i. http://the-url-of-my-image.com

 

[Javier] This is another email!

here is a video:

v. https://www.youtube.com/watch?v=yCj_3_M8fAQ

 

Multiple channels:

If there’s only one Communicator Channel of a certain type, when the audience clicks the app icon, the messages will be displayed automatically. If there’s more than one Communicator Channel, the audience will see a selection screen, where they can choose which feed to display.

 

Message from the audience:

You can write messages on behalf of the Audience, you just need to write "You" as the Character name in the message, if the audience have updated their profile image or name, this will appear in the message.

EG:

t. [John] Hi! how are you?

t. [You] Fantastic!

 

Questions:

The author can write questions that can lead to different stories. When the audience clicks in one of them, the webapp will call Conducttr, you can use this to branch the narrative. Once the audience answers the question, this will be marked as "answered" inside the Communicator so it's ont displayed again. You can post the same question again later if you want.

  • Fixed Answers

When you define this type question the audience will see predefined answers to choose.

You just need to start a new line with a “q.”, each possible answers should be separated by “||”, the matchphrase that will be sent to Conducttr between square brackets everything else will be displayed as the answer to choose

q. [matchphrase] Text || [matchphrase] Text

 

E.G:

q. [p1_yes] Sure! || [P1_no] Of course not!

 

  • Open text answer

You can also choose to allow your audience to answer with an open text answer.

You just need to start a new line with a “o.”, if you want you can add a "question identifier" (this will be added to the API Call and you can use inside your matchphrases to uniquely identify which trigger should fire) and a "promp" between square brackets (this will appear as placeholder in the input box). This can be used to identify the answer inside conducttr and for styling the input box. 

o. [QUESTION_IDENTIFIER,PROMPT]

E.G:

o. [opentext_1,Type your answer: ]

 

When an audience member answers with an open text answer an API Call will be sent to Conducttr with the matchphrase

question [QUESTION_IDENTIFIER] matchphrase [Audience-response]

E.G:

question opentext_1 matchphrase Hey there!

You can use the following matchphrase in an API trigger to capture the response and post it back into the Communicator

opentext |parse('all_chars') as opentext|

Then you can create a Post To Communicator with a line like this

t. [You] |opentext|

 

This will create a post with the audience answer immediately after they send it.

 

You can also search for a matchphrase in the Audience answer to post different responses from your Characters , you just need to add another API trigger with the matchphrase

question [QUESTION_IDENTIFIER] && (YOUR-MATCHPHRASE)

Then you can create a Post To Communicator with the character response:

EG:

t. [Character] Uhmm that sounds interesting

 

You can ave as many triggers with matchphrases as you want, just be careful to write your matchprases and logic in a way they don't fire at the same time, or your audience will receive a lot of different messages at once.

 

 

  • Unlocking pattern

Display a phone like unlocking pattern, the audience has to repeat the pattern in a certain type to unlock somthing.

The pattern starts with a “x.”, an then a text that will be part of the matchphrase (to identify the the trigger) the numeric pattern, the seconds the pattern will be shown to the audience and the time they have to solve it. 

E.G:

x. p1,1234, 5000, 20000

When someone answers it correctly the Communicator will send an API Call to Conducttr with the matchphrase

[YOUR-MATCHPHRASE] [PATTERN]

EG

p1 1259

In the case someone isn't quick enough and the puzzle times out the matchphrase will be:

[YOUR-MATCHPHRASE] 000

EG

p1 0000

 

  • Fixed Answers with a time limit
    • COUNT DOWN

A question with fixed answers, a time limit and a simple countdown progress bar.

You specify how many hours, minutes and seconds the audience will have to answer the question (the countdown starts when they open the app, and "reset" if they refresh the page or open another app)

b. time_out_matchphrase, hh:mm:ss || [matchphrase1] Option1 || [matchphrase2] Option2! 

EG

b. p1_yes, 12:00 || [matchphrase1] Option1 || [matchphrase2] Option2! 

           

    • REACTION TIME

A question with fixed answers, a time limit and countdown progress bar.

You specify how many hours, minutes and seconds the audience will have to answer the question since the message is posted.

 

 r. time_out_matchphrase, hh:mm:ss || [matchphrase1] Option1 || [matchphrase2] Option2! 

EG

r. novote, hh:mm:ss || [matchphrase1] Option1 || [matchphrase2] Option2! 

novote is the matchphrase in case the time runs out

19:05:00 the voting time (hours:minutes:seconds) since the post of the message

 

    • EXPIRATION DATE

A question with fixed answers, a date and time expiration date and countdown progress bar.

You specify the date (or only the time if you want to use the present day) when the question will expire. 

 

e. time_out_matchphrase, hh:mm:ss || [matchphrase1] Option1 || [matchphrase2] Option2! 

e. time_out_matchphrase, DD/MM/YYYY hh:mm:ss || [matchphrase1] Option1 || [matchphrase2] Option2! 

EG

e. novote, 23/03/2015 19:05:00 || [matchphrase1] Option1 || [matchphrase2] Option2!

 

novote is the matchphrase in case the time runs out

19:05:00 the date when the voting ends (if you especify only a time the default date will be the current)

 

3.1 Msngr

3.1.1 What is it?

A chat-like feed to display conversation between characters, or between characters and the audience. Embed images, youtube videos, audios and files.

 

3.1.3 Format of the messages

Each Post to Communicator can contains as many conversation lines as the author want.  These conversation lines can be pure text or embed an image, audio or video. The author can also specify dates to make the content look more realistic.

Each conversation line must be in a separate line and start with a character and a dot. This character defines the type of content (text, image, sound or video) after that you can write the name of the character between square brackets:

  • “t.” Text only
  • “i.” Text and Image: the url of an image
  • “a.” Text and sound: the url of a sound
  • “v.” Text and video: the url of a Youtube video.
  • “d.” date, separator

E.G

d. 21 October 2014
t. [javier] Hi! how are you?
t. [Jessie] Fine, thanks!
d. 22 October 2014
i. [javier] http://an.cr/sa/yshkM
t. [Javier] So do you wanna party tonight?

 

3.2 GoSocial

3.2.1 What is it?

A social network feed to display posts between characters, or between characters and the audience. Embed images, youtube videos, audios and files.

 

3.2.2 Format of the message

Each Post to Communicator  can contains as many posts as the author want.  These conversation lines can be pure text or embed an image, audio or video. The author can also specify dates to make the content look more realistic.

Each conversation line must be in a separate line and start with a character and a dot. This character defines the type of content (text, image, sound or video) after that you can write the name of the character between square brackets:

  • “t.” Post without media.
  • “i.” Post with Image: the url of an image
  • “a.” Post with  Sound: the url of a sound
  • “v.” Post with video: the url of a Youtube video.
  • “c.” comment
  • “r.” reply

E.G

i.[Javier] Hi! This is a post!! http://an.cr/sa/MFf60

i.[Javier] Hi! This is a post!! http://an.cr/sa/MFf60

c. [Jessie] Hi, I like this :) !

r. [Jessie] ;)

 

3.3 Microblog

3.3.1 What is it?

A microblogging feed to display small posts between characters, or between characters and the audience. Embed images, youtube videos, audios and files.

3.3.2 Format of the message

Each Post to Communicator  can contains as manymicroblogging lines as the author want.  These conversation lines can be pure text or embed an image, audio or video. The author can also specify dates to make the content look more realistic.

Each conversation line must be in a separate line and start with a character and a dot. This character defines the type of content (text, image, sound or video) after that you can write the name of the character between square brackets:

  • “t.” Tweet without media, only text.
  • “i.” Tweet with Image: the url of an image
  • “a.” Tweet with  Sound: the url of a sound
  • “v.” Tweet with video: the url of a Youtube video.

E.G

t. [Javier] Tonight is the night!!

i.[Javier] Partayyy!! http://an.cr/sa/MFf60

v.[Jessie] Yeah! https://www.youtube.com/watch?v=yCj_3_M8fAQ

 

3.4 Mail

3.4.1 What is it?

A mail manager app to display emails from characters, or between characters and the audience. Embed images, youtube videos, audios and files.

3.4.2 Format of the message

Each Post to Communicator  can contains as many mails as the author want.  These emails can be pure text or embed an image, audio or video.

To embed an image, audio, video or a file you just need to start a new line with :

  • “a.” An audio: the url of an audio
  • “i.” An Image: the url of an image
  • “v.” A youtube video: the url of a video

E.G

[Javier] Welcome to the Newsletter

this is the body

i. http://the-url-of-my-image.com

[Jessie] hi!

this another body

and this another line for the same body

and this another line for the same body

 

Each email should start with the name of the character between square brackets “[]”. The text that follows the name will be displayed as the Subject, and all the next lines will be the body (until the next character name “[character]”)

 

3.5 Blog

3.5.1 What is it?

A Blog to display posts from characters. Embed images, youtube videos, audios and files.

3.5.2 Format of the message

Each Post to Communicator  can contains as many blog posts as the author want.  These posts can be pure text or embed an image, audio or video. 

To embed an image, audio, video or a file you just need to start a new line with :

  • “a.” An audio: the url of an audio
  • “i.” An Image: the url of an image
  • “v.” A youtube video: the url of a video

E.G

[First Entry of the Blog] SubTitle

this is the body

i. http://the-url-of-my-image.com

[Second Entry of the Blog] hi!

this another body

and this another line for the same body

and this another line for the same body

 

Each blog post should start with the name of the character /title of the post between square brackets “[]”. The text that follows the name will be displayed as the Subject, and all the next lines will be the body (until the next character name / title “[character]”)

 

3.6 Files

3.6.1 What is it?

Located in the bottom menu bar, the Files folder is a depositbox to keep important files and documents.

3.6.2 Format of the message

In order to add documents to your Files folder, you need to create a Communicator channel, and select custom-> "media" as the type.

Each Post to Communicator can contains as many files or documents as the author want.  These posts can be links to files, embed an image, audio or video. Every file should be in a new line. 

E.G

[Important File] http://the-url-of-my-image.com

[Important Video] http://youtube.com/video-id

 

Each file should start with the name of the file (the name you want to display, no the real one) between square brackets “[]”. The text that follows is the URL that contains the file.

4 Stand-alone version


If you are using the standalone version you need to install the Communicator code (you can find it HERE) in your server or web hosting.

 

4.1 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

4.1.1 Ingredients

You will need:

  1. a Web host (With PHP and a MySQL Database)
  2. a Conducttr project

4.1.2 Preparation

To prepare, you’ll need to:

  1. Create a new API entry inside Conducttr called “Communicator”
  2. Setup your web host

5.1.2.1 Setting up the web host

  1. Register a domain name (e.g. http:5//ww.zenfilms.com).  In this document will be using MYURL to indicate where you should replace with your domain name
  2. Ensure that your server runs PHP release 5 or higher. Our code will not work with PHP 4
  3. Create a new MySQL Database on your web server. Import the Communicator database structure (you can find it HERE) into your database.

 

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

 

4.1.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

4.1.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 kwow which database and project we are using.

  1. Update the “config.php” code snippet with details from your project.

 

You need to update the following information:

 

  • 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.

 

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

Add your project details into the "projects" table of your Database:

    • PROJECT_ID: You can find at the top of Conducttr

    • Inside the API panel:
      • CONSUMER_KEY
      • CONSUMER_SECRET
      • ACCESS_TOKEN
      • ACCESS_TOKEN_SECRET

4.1.4    Implement the logic in your Conducttr project

Once we have upload everything to our web host, we will configure the video list, the video size and the video triggers all inside Conducttr.   Also we will determine the interaction between the audience and the Communicator.

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

Comments