Skip to main content

Installation

Pre-requisites​

Altogic client library allows you to access the Altogic services from your web/mobile applications. In order to use the Altogic client library you need to create an app, deploy your app to an environment and a client key in Altogic. Optionally, you might also need to get your API Key which is used to manage access to your cloud functions.

info

When you create an app, Altogic creates an environment for you, deploys your app to this environment and creates a master client key that you can custimize later by default. You can access the all the required information (e.g., client key, base URL) to initialize the client library from the Home view of you app in Altogic Designer.

Creating an account in Altogic​

To create an account in Altogic, you can visit the Designer which is the core visual development tool that you use to design, develop and deploy your backend applications.

Creating an app​

You can create an app with the Designer. To create an app via the Designer:

  1. Log in to Altogic with your credentials.
  2. Select New app.
  3. In the App name field, enter a name for the app.
  4. In the Sub domain field, enter a sub-domain for the app.
  5. In the Execution environment region field, select a region for the app. This will be the location where your app's initial environment will be created.
  6. In the Execution environment pricing plan field, select available pricing plan for your environment.
  7. In starter templates section, select the Basic template
  8. Select Create.
  9. Click/tap on the newly created app to launch the app.
https://designer.altogic.com

Creating client key​

You can create a client key to control access to your app's services and define the access rights of each of the key modules of the client library. When you create a new application your client key will be automatically created for you.

You can create a new client key and manage existing ones using the Designer. To create a client key via the Designer:

  1. Launch the Designer.
  2. From your workspace, selec the application that you would like to manage its client keys.
  3. Click/tap on App Settings at the left-bottom of the designer.
  4. Click/tap on Client library keys section.
  5. Click/tap on New client key button.
  6. In the Client key name field, enter a client key name for the app.
https://designer.altogic.com
  1. (Optional) In order to protect your application, Altogic can restrict the client library to make calls only from "Authorized Domains". In the Advanced section, by selecting Only authorized domains you can restrict domains of the client key.
  2. (Optional) Altogic can cap the client library RESTful API requests, namely the requests made from database, cache, storage, message queue and task modules in a specific timeframe. Altogic can also cap the number of realtime messages that can be sent in a specific timeframe. In the Rate limiting section, you can set the RESTful API and Realtime rate limiters.
https://designer.altogic.com

Getting environment url​

You can create a new environment or access existing app's envUrl from the Environments view in Altogic Designer.

There are two types of envUrl that you can use when creating your Altogic client; subdomain or base URL. You can send a request to Altogic services using any of the base URL or subdomain information. The subdomain information can be updated via the Environment view, but the default base URL information cannot be changed. If you want to access Altogic services using different libraries (E.g., http, fetcher, axios), we recommend you to use your base URL information. To get the envUrl via the Designer:

  1. Launch the Designer.
  2. Click/tap on Environments at the left-bottom of the designer.
  3. Click/tap name of the Environment
  4. Scroll down to API BASE URL section.
  5. Copy subdomain or environment url.
https://designer.altogic.com

Creating an API key (Optional)​

As an option, you might also need to get your apiKey which is used to manage access to your cloud functions. The access rights of your app endpoints are managed through API keys in your environments. To create an API key via the Designer:

  1. Launch the Designer.
  2. Click/tap on Environments at the left-bottom of the designer.
  3. Click/tap name of the Environment
  4. Click/tap on API Keys section.
  5. Create a new API Key by clicking on New API Key button.
https://designer.altogic.com
info

The API key is different than the clientKey used when creating an instance of Altogic client library. clientKey is primarily used to manage access rigths of the client library whereas apiKey is used to manage access to your app endpoints.

The main reason why there are two different keys is that you can call your app cloud functions using any other http client (e.g., axios, fetch) using the API key and you are not restricted to use Altogic's client library. However, we strongly recommend using our client library which significantly eases app development and integration of your frontend to your Altogic backend.

Library Installation​

Using package manager​

You can install the Altogic client library with package managers like npm, Yarn or pub for dart:

npm install altogic

If you're using a bundler (like webpack), you can import the Altogic and create your Altogic client instance. The creation of client library requires two required parameters; envUrl and clientKey. The envUrl is the base URL of the Altogic application environment where a snapshot of the application is deployed and clientKey is the client library key of your app.

~ /src/altogic.js
import { createClient } from "altogic";

// Create a client for interacting with Altogic backend app
// You need to provide `envUrl` and `clientKey` as input parameters
// Optionally, you can provide `apiKey`, `signInRedirect` and `realtime` parameters
// in options. More details can be found in the Options section

let envUrl = "https://c1-na.altogic.com/e:6233230ba1c78fcb1ad5919a";
let clientKey = "f59c9ef3a53b40669c6a79a62593e153";

const altogic = createClient(envUrl, clientKey);

CDN​

To install with a CDN (content delivery network) add the following script to import Altogic client library.

<script src="https://cdn.jsdelivr.net/npm/altogic"></script>

Then you can use it from a global altogic variable:

<script>
  const { createClient } = altogic;
  //Create a client for interacting with Altogic backend app
  //You need to provide `envUrl` and `clientKey` as input parameters
  const client = createClient(
    "https://c1-na.altogic.com/e:6233230ba1c88fcb1ad5919a",
    "f59c9ef3a53b40669b6a79a62593e153"
  );
</script>

Initialization options​

You can initialize the client library with apiKey, signInRedirect, and localStorage options.

import { createClient } from "altogic";

// Create a client for interacting with Altogic backend app
// You need to provide `envUrl` and `clientKey` as input parameters
// Optionally, you can also provide `apiKey`, `signInRedirect` and `realtime` options

let options = {
  apiKey: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbnZJZCI6IjYyYzE0MDQ5...',
  signInRedirect: 'http://localhost:3000/auth-redirect',
  realtime: {
    autoJoinChannels: false,
    bufferMessages: true,
    echoMessages: true,
    reconnectionDelay: 2000,
    timeout: 30000
  }
}

const altogic = createClient(envUrl, clientKey, options);
info

By default Altogic client library uses Window.localStorage of the browser.

  • If you prefer to use a different storage handler besides Window.localStorage or if you are using the Altogic client library at the server (not browser) then you need to provide your storage implementation.

Parameters​

Here you can find parameters for the createClient method.

#

Name

Data type

Required

Description

1envUrlStringYesThe base URL of the Altogic application environment where a snapshot of the application is deployed.
2clientKeyStringYesThe client library key of the app
3optionsClientOptionsNoAdditional client library options.

Client Options​

Here you can find properties for the ClientOptions

#

Name

Data type

Required

Description

1apiKeyStringNoThe unique app environment API Key which needs to be created using the Designer. The apiKey is passed in Authorization Header when making RESTful API calls to your app endpoints. This key is different than the clientKey used when creating an instance of Altogic client library. clientKey is primarily used to manage access rigths of the client library whereas apiKey is used to manage access to your app endpoints.
2localStorageClientStorageNoIf you prefer to use a different storage handler besides Window.localStorage you need to define localStorage option. You need to define an object having following methods,
1. setItem(key:string, data:object)
2. getItem(key:string)
3. removeItem(key:string)
3signInRedirectStringNoThe sign in page URL to redirect the user when user's session becomes invalid. Altogic client library observes the responses of the requests made to your app backend. If it detects a response with an error code of missing or invalid session token, it can redirect the users to this sign in URL.
4realtimeRealtimeOptionsNoThe configuration parameters for websocket connections.

Realtime Options​

Here you can find properties for the RealtimeOptions

#

Name

Data type

Required

Description

1autoJoinChannelsBooleanNoThe flag to enable or prevent automatic join to channels already subscribed in case of websocket reconnection. When websocket is disconnected, it automatically leaves subscribed channels. This parameter helps re-joining to already joined channels when the connection is restored. By default true.
2bufferMessagesBooleanNoBy default, any event emitted while the realtime socket is not connected will be buffered until reconnection. You can turn on/off the message buffering using this parameter.
3echoMessagesBooleanNoThe flag to enable or prevent realtime messages originating from this connection being echoed back on the same connection. By default true.
4reconnectionDelayIntegerNoThe initial delay before realtime reconnection in milliseconds. By default 1000 milliseconds.
5timeoutIntegerNoThe timeout in milliseconds for each realtime connection attempt. By default 20000 milliseconds.