idmo/cola-bubble-1

Base repository for development of a bubble for Cola Messenger

cola-bubble

This repository contains the source code and dependencies to start developing a Bubble for Cola Messenger, the new group messaging platform from Cola.

Download Cola Messenger for iPhone

Getting Started

To begin building bubbles for Cola Messenger, follow these steps:

1. Configure the Development Environment
2. Install Cola Messenger (iOS only)
3. Request a Developer Configuration Profile
4. Hello World Bubble

• Build
• Install
• Debug
• Test

Next you can build your own bubbles or see more examples.

Configure Development Environment

Cola Bubbles use React Native which requires Node.js. To get started, install the following:

1. Node.js v5.6.0 (required) Node.js is the JavaScript runtime used for bundling bubbles (Note: v5.6.0 is the approved version)
2. Atom (optional) IDE recommended by Facebook for developing React Native apps
3. Nuclide (optional) Atom plugin with support for React, JSX, Flow
4. Chrome (optional) Google Chrome Developer Tools can be used for debugging bubbles if Atom/Nuclide isn't installed

Check that npm (Node Package Manager) is installed or install npm (if needed)

$ which npm
/path/to/npm

BDK Sources

To obtain BDK sources just fork this repo (cola-bubble) and then clone the fork. In your local clone of cola-bubble execute npm install to complete installation.

$ cd /path/to/cola-bubble
$ npm install

Note: this will download dependencies into node_modules and may take some time, depending on network speed.

Install Cola Messenger

Install Cola Messenger and follow the prompts to register with Cola.

Cola works best with groups, so make sure to invite your family and friends to Cola so they can help you test your new Cola Bubble!

Development Profile

Request a signed Cola Development Profile.

Note: the Development Profile Identifier (ex. com.yourcompany.) must prefix all Bubble identifiers that run with this profile (ex. com.yourcompany.yourbubble)

Cola will deliver your profile via email. To install, open the email on iPhone using iOS Mail app and tap the Cola Development Profile attachment. When prompted, find and tap Copy to Cola (might need to scroll the app icons to find Cola).

Once Cola Messenger opens, tap Install. View the installed Cola Development Profile in Cola Messenger in Settings/Developer section. Once you've installed a bubble, tap a given Developer item to see installed bubbles associated with that Development Profile.

Hello World Bubble

Now we'll build, install, debug, and test the most simple bubble, the included Hello World bubble example (located in HelloWorld directory at the root of cola-bubble).

$ cd /path/to/cola-bubble
$ ls HelloWorld/

First open HelloWorld/manifest.js and update identifier to be compatible with the identifier in your Development Profile by changing com.yourcompany.HelloWorld to use your identifier. For example, if Development Profile has identifer io.cola. then manifest.js is updated as:

 {
   "format" : 1,
-  "identifier" : "com.yourcompany.HelloWorld",
+  "identifier" : "io.cola.HelloWorld",
   "version" : 1,
   "name" : "Hello World!"
 }

Build

Build the Hello World bubble by running the bubbler in build mode (see BDK Sources if cola-bubbles/node_modules is missing).

$ cd /path/to/cola-bubble
$ node node_modules/cola-tools/bubbler build --development --source ./HelloWorld --destination /path/to/bubbler/output/

$ ls -R /path/to/bubbler/output
com.yourcompany.HelloWorld

/path/to/bubbler/output//com.yourcompany.HelloWorld:
1

/path/to/bubbler/output//com.yourcompany.HelloWorld/1:
index.bundle	index.map	manifest.json

Install

Install your Hello World bubble in Cola Messenger by transferring the bubbler output via a built-in WebDAV server, the Cola Development Server. To enable the Cola Development Server, open Cola Messenger, navigate to Settings/Developer section and toggle the Cola Development Server switch.

Note: it is recommended to disable auto-lock on iPhone and keep Cola Messenger active before connecting to Cola Development Server and while transferring bubbles (currently WebDAV port will change if Cola Messenger becomes inactive or iPhone locks or sleeps).

Now transfer the Hello World bubble folder to Cola Messenger using a WebDAV client (ex. Transmit, CyberDuck). Usually Bonjour is the easiest way to connect to Cola Developer Server. There is no password for Cola Development Server so use Guest or Anonymous when connecting. Drag the entire folder (ex. /path/to/bubbler/output/com.yourcompany.HelloWorld) to the root directory of the Cola Development Server.

If installed successfully, Hello World bubble will now be available in the Bubble Menu (likely near the bottom, might need to scroll to find). Development bubbles are also listed in Settings/Developer section under the Developer item.

Now open an existing Cola conversation or create a new Cola group and send a Hello World bubble.

Note: anyone who hasn't yet installed the Hello World bubble won't see this bubble until they are given the Hello World bubble (see Testing).

Debug

Debug your Hello World bubble using Atom/Nuclide or Google Chrome.

Note: it is recommended to disable auto-lock on iPhone and keep Cola Messenger active when debugging (currently WebDAV port will change if Cola Messenger becomes inactive or iPhone locks or sleeps).

Ensure that bubble debugging is enabled in Settings/Developer section by toggling Cola Bubble Debugger switch.

Currently only one bubble can be enabled for debugging. By default the most recently transferred bubble will be the enabled debugging bubble. Verify that the correct bubble is enabled by reviewing the list of bubbles for the active developer under Settings/Developer section Developer item. If necessary, toggle the debugging switch for the desired bubble.

Now run the bubbler in debugger mode, where <ip>:<port> are the values displayed in Settings/Developer section under Cola Development Server.

$ cd /path/to/cola-bubble
$ node node_modules/cola-tools/bubbler debugger --connect <ip>:<port> --source ./HelloWorld/

 ┌────────────────────────────────────────────────────────────────────────────┐ 
 │  Running packager on port 8081.                                            │ 
 │                                                                            │ 
 │  Keep this packager running while developing on any JS projects. Feel      │ 
 │  free to close this tab and run your own packager instance if you          │ 
 │  prefer.                                                                   │ 
 │                                                                            │ 
 │  https://github.com/facebook/react-native                                  │ 
 │                                                                            │ 
 └────────────────────────────────────────────────────────────────────────────┘ 

Note: if Error: connect ETIMEDOUT or Error: connect ECONNREFUSED check that Cola Messenger is foregrounded and active, Cola Development Server is enabled and <ip>:<port> are correct (may need to exit/enter Settings to get current values).

If you're using Atom/Nuclide, open Nuclide menu and select React Native/Start Debugging. If you're using Chrome, make sure Chrome is running.

Now cause a debug bubble to be instantiated by either navigating to this bubble in an existing conversation or composing this bubble via Bubble Menu. The debugger will attach to the first instance of a debug bubble.

To have the Atom/Nuclide or Chrome debugger pause on exceptions, choose the Sources tab, toggle the pause/stop button and check Pause On Caught Exceptions.

Note: when bubbler is in debugger mode, source changes will be picked up each time a bubble is instantiated so it is not necessary to build and install bubbles; just save your code and the next time your bubble is instantiated you will see your changes!

Test

Test your Hello World bubble with family and friends. To test a bubble you'll need to email your testers a) your Testing Profile and b) your Cola Bubble.

Currently a Testing Profile is the same as a Development Profile. Forward the email you received containing your Development Profile to anyone who will be testing your bubble. Have your testers open the email on iPhone using iOS Mail app and install the profile (which will enable them to install and test your bubble).

Build your bubble in release mode (omit the --development flag).

$ cd /path/to/cola-bubble
$ node node_modules/cola-tools/bubbler build --source ./HelloWorld --destination /path/to/bubbler/output/

Make sure there is a single version of your bubble in the bubbler output folder.

$ cd /path/to/bubbler/output/
$ ls com.yourcompany.HelloWorld/
1

Note: if you have more than a single version folder remove any unwanted version folders.

Create a HelloWorld.bubble folder and move com.yourcompany.HelloWorld inside.

$ cd /path/to/bubbler/output/
$ mkdir HelloWorld.bubble
$ mv com.yourcompany.HelloWorld/ HelloWorld.bubble/
$ ls -R HelloWorld.bubble/
com.yourcompany.HelloWorld

HelloWorld.bubble//com.yourcompany.HelloWorld:
1

HelloWorld.bubble//com.yourcompany.HelloWorld/1:
index.bundle	index.map	manifest.json

Note: there can only be a single bubble folder inside a .bubble container folder.

Use the OSX Mail app on your mac to email your bubble to your testers. Compose an email to your testers and drag HelloWorld.bubble into the email so Mail can attach and zip it automatically.

Testers should open the email on iPhone using iOS Mail app, tap the HelloWorld.bubble attachment and Copy to Cola when prompted. You can install your emailed bubbles this way as well to verify that your bubble is packaged correctly for your testers.

Build Your Own Bubbles

Cola Bubbles are currently built on React Native v28 and support several fundamental React Native Components, including:

View
ScrollView
ListView
Image
Text
TextInput
Alert
TouchableHighlight
TouchableOpacity
TouchableWithoutFeedback

Import these components as follows:

const {
  Text,
  View,
} = require('react-native')

Other components are available by requiring directly:

const Navigator = require('Navigator')

Note: Cola may disable certain React Native components that are incompatible with Cola Bubbles. Please contact us if you need a disabled component.

Example Bubbles

There are more example bubbles available in cola-examples, and any public forks of the cola-bubble repo can be browsed as well. Happy bubbling!