Getting Started

To start sending messages, you will create a Cogswell.io account with an access key, and a client (in the language of your choice) with a client key.  When you're ready, submit your entry using Github or Bitbucket.

Contest Rules

Register for an Account

1. Go to https://cogswell.io/#!/
2. Click on Sign Up
3. Fill out account information
4. Click the Sign Up button located at the bottom of the form
5. Follow instructions in e-mail to register account

Follow Quick Start Guide

This guide will help you get started and explain what the different pieces of Cogs can do. It might be good to get a simple proof of concept done then from there create more complicated rules that can be used for your application.

Quick start guide located here

Create a Github or Bitbucket Repository for Your Entry

Bitbucket

https://confluence.atlassian.com/bitbucket/create-a-git-repository-759857290.html

Github

https://help.github.com/articles/create-a-repo/

Create README

Create a README.md file at the root of the repository. The contents of the README are described in the contest rules.

Create a Client Key

Through Web UI (Recommended)

1. Go to the Web UI
2. go to Setup → Client Keys
3. In the drop down box: select the API key you would like to use to create the client secret and salt
4. Press create keys
5. Copy and paste into your application
6. Client keys are not stored on the Cogs server

Through Java Test Tool

All of the events sent to the server are secured by your client key,So long as the client secret key is kept secret, no other client can spoof requests to your cogswell.io namespace.

Here is how to create one for your app:

1. Download the Java Test Tool from https://cogswell.io/#!/api-docs
   1. Requires Java 8. The app will throw a {{java.lang.UnsupportedClassVersionError}} if Java 8 is not installed, or correctly pathed on your system. See Resolving Java 8 problems
   2. There are various bugs with Java not pathing correctly after installing new versions of Java. This has been confirmed to happen on both OSX and Windows.
2. Unzip it, and run it from the command line (bin/cogs-java-example-app on Linux or bin/cogs-java-example-app.bat on Windows)
3. Enter your server Access and Secret keys (cogswell.io > Setup > Keys > Select the key you already created)
4. Click on the Generate Client Key tab, and click Generate Client keys. 
5. When the SDK or the API requires the Client Secret and Client Salt, use these values.

You can generate as many of these keys as you need: they are intended to be used as one key per app.  For details, you can check out the user manual: https://aviatainc.atlassian.net/wiki/display/COGS/Web+App+User%27s+Manual#WebAppUser'sManual-Keys.   

Download SDK

The next step is to begin writing your application. We have a list of SDKs below, all of which contain build instructions and example code. If none of them are in the language you would like to write your application in, the underlying implementation of Cogs is just a REST API, so any language can be used by referencing our API documentation.

• REST API documentation
• SDK download page 

SDK Overview

Although the API may appear complicated at first glance, interaction with Cogs is really just two concepts:

1. Sending Events containing Data
2. Subscribing to a topic(s) so you app can receive messages published to that topic(s).

Your code base really only needs to interact with these two operations, but with these two you can build a powerful application.

The SDK has the following capabilities:

• Send Events to Cogs
  
  • The following is required to send an event
    • timestamp
      • The current time in ISO-8601 format (used to prevent "replay" attacks, backend validates timestamp is no older than one minute)
    • client_salt
      • The client secret and salt pairs are for authentication so your API secret key does not live on any sort of client side application
      • This is generated from the API using the /client_secret endpoint: documentation found here https://cogswell.io/docs/api/#!/Client_secret/post_client_secret
    • event_name
      • Any arbitrary string that can be provided to name the event
      • Present to help you keep track of different type of events you may want to send for a particular namespace
    • access_key
      • This is generated in the Cogswell web application
    • namespace
      • The namespace name that you want to send your event to
    • attributes
      • A map from the attribute name to the attribute value you want to pass.
      • These are defined when the namespace is created
• Subscribing to a topic (to receive messages published to that topic)
  • Messages from Cogs are sent to everybody listening to a specific "Topic"
    • Topics are defined by the combination of all primary key attributes in a namespace
  • Android and iOS
    • Your application must first be registered in the Cogs Web app, documentation found here Web App User's Manual
    • Register application
      • Necessary fields can be found here: https://cogswell.io/docs/api/#!/Register_push/post_register_push
    • When a notification is received you will also receive a message Token ID, which can then be used to fetch the contents of the message using the appropriate function and the token that was just received
  • C#, Java, and Javascript
    • REST endpoint documentation: https://cogswell.io/docs/api/#!/Push/get_push
    • The following is required to create a websocket
      • timestamp
        • The current time in ISO-8601 format (used to prevent "replay" attacks, backend validates timestamp is no older than one minute)
      • client_salt
        • The client secret and salt pairs are for authentication so your API secret key does not live on any sort of client side application
        • This is generated from the API using the /client_secret endpoint: documentation found here https://cogswell.io/docs/api/#!/Client_secret/post_client_secret
      • access_key
        • This is generated in the Cogswell web application
      • namespace
        • The namespace name that you want to connect to and listen for events from
      • attributes
        • The attributes that make up the primary key for a namespace are the only ones that need to be included
        • This will determine which topic you are listening to 

Importing the SDK to your project

"dependencies": {
	"cogs-javascript-sdk": "1.0.3"
}

Send your first event

Once your client is compiling and running, try sending an event.  

If you have set up notifications, send a matching event.  The Cogswell service will attempt to send the message to every client that is listening for notifications on that topic: Android, iOS, and each WebSocket.

If you have created a segment that filters a set of users, for example, you can watch as the number of users increases or decreases.  In your web account, open Namespace Segments, scroll to the bottom of the page, and have a look at the list of segments you have created.  Click the small refresh icon in the top right corner of the segment panel and you'll see when the number of users in the segment changes.  For details on segments, check out https://aviatainc.atlassian.net/wiki/display/COGS/Web+App+User%27s+Manual#WebAppUser'sManual-NamespaceSegments