Ekko client

A JavaScript client for Ekko, the realtime serverless platform.

If you have not already done so, you should first deploy your Ekko infrastructure using the Ekko CLI https://github.com/ekko-realtime/cli

Download ekko-client

Download Ekko client from any of the following sources:

Use the CDN

<script src="https://d3irfuxwybyrt2.cloudfront.net/ekko-client-v2.2.6.js"></script>

Use a package manager

npm install ekko-realtime-client

Get the source code

https://github.com/ekko-realtime/client

Initialization

Description

Use this method to initialize the Ekko client. At a minimum you will need to provide the host endpoint and a valid JWT which can be generated with the Ekko CLI

Method

Ekko( {String host, String JWT, String AppName, String UUID} )

| Parameter | Type | Required | Defaults | Description | | :-------- | :----- | :------- | :---------------------- | :-------------------------------------------------------------------------------------------------------------------------- | | host | String | Yes | | URL endpoint for your Ekko server provided by your Ekko CLI | | JWT | String | Yes | | App specific JWT for authenticating your Ekko client instance provided by your Ekko CLI | | AppName | String | Yes | | Name of the application you are working on. Used for message routing | | UUID | String | Optional | Randomly generated UUID | Unique identifier for each user. Useful for maintaining user state across devices |

Note: https://www.npmjs.com/package/lil-uuid is an NPM package that can be used to generate UUID's

Basic Usage

Applications can initialize the Ekko client object by passing the host and JWT provided by your Ekko CLI. Each client will also need the appName that was used to generate the JWT. Each client should also pass a UUID that represents the user or the device that connects to th Ekko server.

const ekko = new Ekko({
  host: "myEkkoServerEndpoint",
  jwt: "myAppJWT",
  appName: "myAppName",
  uuid: "myUniqueUUID",
});

Event Listeners

Description

You can add callback functions to status, message, and presence events using the addListener method.

Adding Listeners

ekko.addListener({
  status: (ekkoEvent) => {
    const event = ekkeEvent.event // Description of the event that occurred
    const app = ekkoEvent.app; // App that the event occurred on
    const admin = ekkoEvent.admin; // True if user that triggered event is an Admin, False otherwise
  },
  message: (ekkoEvent) => {
    const message = ekkoEvent.message; // Message object
    const channel = ekkoEvent.channel; // Channel on which the message was published
    const uuid = ekkoEvent.uuid; // Message publisher
  },
  presence: (ekkoEvent) => {
    // TODO: FILL OUT
  },
});

Listener Status Events

TODO: FILL OUT

Listener Presence Event

TODO: FILL OUT

Publish

Description

The publish() method is used to send a message to all subscribers of a channel within the same app as teh publisher.

Publish Anytime

The publisher can only publish to other users within the same app, but they do not necessarily need to be a subscriber to the channel they are publishing to.

Message Data

The message argument can be any valid JavaScript object. You are able to define any properties you need to meet your app's requirements.

Method

publish(Object message, String channel)

| Parameter | Type | Required | Defaults | Description | | :-------- | :----- | :------- | :------- | :------------------------------------------------ | | message | Object | Yes | | The message may be any valid JavaScript object. | | channel | String | Yes | | Specifies channel name to publish messages to. |

Basic Usage

ekko.publish({
  channel: "my_channel",
  message: {
    text: "my message text",
    otherProperty: "any other data you need to pass to subscribers",
  },
});

Subscribe

Description

This method causes the client to create an open TCP socket connection to the Ekko server and begin listening for messages on a specific channel.

Method

subscribe({Array channels, Boolean withPresence})

| Parameter | Type | Required | Defaults | Description | | :------------- | :------ | :------- | :------- | :-------------------------------------------------------------------------------------------------- | | channels | Array | Yes | | Specifies the channels to subscribe to. It is possible to specify multiple channels as an array | | withPresence | Boolean | Optional | False | If true it also subscribes to presence events |

Basic Usage

Subscribe to single channel

ekko.subscribe({
  channels: ["my_channel"],
});

Subscribe to multiple channels

ekko.subscribe({
  channels: ["my_channel_1", "my_channel_2", "my_channel_3"],
});

Subscribe with presence

ekko.subscribe({
  channels: ["my_channel"],
  withPresence: true,
});

Accessing Ekko client information

Description

Ekko client information is stored on the ekko instance and can be accessed.

Host

ekko.host // Ekko server host endpoint URL

uuid

ekko.uuid // Ekko client instance uuid

Host

ekko.appName // Ekko app name

Open Source Development

Update Distribution File

Description

Ekko is an open source project - modification and further development is encouraged!

The distribution files within the /dist directory are useful when developing front-end only applications. This file contains all of the necessary dependencies to run Ekko client. These are the files that are uploaded to the Ekko CDN.

Changes to the Ekko client code should be made within /lib/ekko.js. If you changes are made, you will need to make a new distribution file. There are two ways to make a new distribution file detailed below.

Methods

Automatic distribution file creation (for development)

Run the following command in your terminal from the root of the Ekko client project directory. When any changes are made to lib/ekko.js, a new distribution file will be generated within the /dist directory. This file will be named based off the current npm project version and will overwrite any file that has the same name. This distribution file will not be minified to allow for easier troubleshooting.

npm run watch

Manual distribution file creation (for production)

When you are ready to generate the production version of your distribution file, run the below command to generate a new distribution file in the /dist directory. This file will be named based on the current npm project version and will overwrite any file that has the same name. This distribution file will be minified to reduce the size.

npm run build