Tutorial

The goal of this tutorial is to show you what goes into a collaborative Cola Bubble. It includes the full source code, with comments of a weather bubble similar to the How’s Your Weather Bubble that ships with Cola Messenger.

Collaborative Cola Bubbles ask the recipient of a message to do something or interact with a bubble. For example, tapping on an item in the Quick Poll bubble, or providing your location in the Where Are You Now bubble. These bubbles require some kind of database to manage state. Therefore, they’re more complex than a regular bubble.

Prerequisite

The sample code in this tutorial will not work unmodified. If you want to try running the code on your device, you will need the following:

If you haven’t already, we recommend reading the Getting Started page on Cola developer section of our website. It includes instructions on how to install the Bubble Development Kit.

Weather Underground API Key

You need an API key from Weather Underground. If you don’t already have one, you can get one for free on their website, it’s called the Stratus Plan.

https://www.wunderground.com/weather/api

Tip
If you don’t have an API key, you need to register as a developer. After you log in, click on the “Explore My Options” button. Select the free Stratus plan. Don’t forget to activate your API to make sure it’s working.

Your API should be a 16 character string and look something like this:
5e7c49bedxxxxxxx

Firebase API Key

This sample code is designed to work with Firebase. For your own bubbles, you can use different databases. However, we highly recommend Firebase.

https://www.firebase.com/login/

Fork the Project from the Repo

The source code is available our public repo at:
https://github.com/colahq/cola-examples.git

Once downloaded, you should see the following files and directories.

access.js
compose.js
forecast
index.js
manifest.json
maximize.js
minimize.js
package.json
payload.js
resources
utilities.js
wundergroundapi.js

Let’s take a quick look at the files and folders in this project.

wundergroundapi.js
This module implements the interfaces for interacting with the API provided by the Weather Underground.

resources/
This folder contains all your assets such as graphics for icons and artwork. We recommend using PNG files for graphics. Be sure to include 2x and 3x of your files.

forecast/
This folder contains different components for displaying the forecast information you retrieve from the API.

utilities.js
This file provides a set of utility functions for other components.

access.js
The Access component is used to display a full screen prompt for access to the location service. Although written specifically for the “location” service, this same component could be repurposed for any other service or for all privacy services.

manifest.json
This module provides metadata for your app. Think of it like a preferences file. This is where you will enter your Cola Developer ID and set paths for assets.

package.json
This module includes metadata about your bubble.

payload.js
This module is responsible for managing all of the payload data. For this collaborative bubble, it combines the immutable data from the conversation stream as well as dynamic data from Firebase.

index.js
This is the main entry point for the bubble. Based upon the bubble mode, it will add the proper component for display.

compose.js
The Compose component is used as the top-level display of the bubble when it’s in setup mode.

minimize.js
The Minimize component is used as the top-level display of the bubble when it’s in either of the BUBBLE_OUTGOING_MODE or BUBBLE_INCOMING_MODE modes. If you’ve used Cola this is the Bubble view when it’s inline in a converation.

maximize.js
The Maximize component is used as the top-level display of the bubble when it’s in either of the BUBBLE_FULL_OUTGOING_MODE or BUBBLE_FULL_INCOMING_MODE modes. If you’ve used Cola think of this as the full screen mode of a Bubble.

Go to Page 2 – Getting Started