geotrigger.js

An API client for the ArcGIS Geotrigger Service.

Features
Examples

Authenticating as an application
Authenticating as an existing device
Authenticating as a new device

Documentation
Geotrigger.Session(options) * Options * Methods * Properties * Events * Persisting Authentication * Expiring Tokens
Browser Support and Proxies
Development Instructions
Resources
Issues
Contributing
Licensing

Features

CORS support
No dependencies
Handles authentication, persisting and refreshing sessions
Works in browsers and in Node.js

Examples

As an application with `clientId` and `clientSecret`

This method is best for server-side applications, or any client-side application where you don't mind giving total access to your application to the user.

var geotriggers = new Geotrigger.Session({
  clientId: "ABC",
  clientSecret: "XZY"
});

geotriggers.request("trigger/list", {
  tags: ["portland"]
}, function(error, response, xhr){
  console.log(error, response, xhr);
});

BE EXTEMELY CAREFUL EXPOSING YOUR CLIENT SECRET! If a user gains access to your client secret they have access to your ENTIRE Geotrigger based application and can do whatever they want. As a result this is generally best for server-side applications that can hide the clientSecret from potentially malicious users.

As an existing device

If you have a refreshToken for a device, you can pass that to create a new session. token, expiresOn, and deviceId are all optional but will give Geotrigger JS more information to work with so they should be passed if availble.

var geotriggers = new Geotrigger.Session({
  clientId: "ABC",
  refreshToken: "A VALID REFRESH TOKEN FOR THE DEVICE",
  token: "A TOKEN FOR THE DEVICE",
  expiresOn: "THE TOKEN EXPIRATION DATE",
  deviceId: "THE DEVICE ID"
});

geotriggers.request("device/info", function(error, response, xhr){
  console.log(error, response, xhr);
});

This kind of workflow would be ideal for applications where users can edit their own triggers on the web. A server would store the refeshToken and pass it to the page where a session could be initiated.

As a new device

Geotrigger JS can also automatically register a new device for you. This approch is similar to the mobile SDKs for iOS and Android which will register an anonymous device that can access the API.

var geotriggers = new Geotrigger.Session({
  clientId: "ABC"
});

geotriggers.request("device/info", function(error, response, xhr){
  console.log(error, response, xhr);
});

Documentation

Geotrigger.Session(options)

The core object of Geotrigger JS is the Session object. You can initialize a session in a variety of ways depending on the kind of application you are trying to create.

As An Application
As An Existing Device
As A New Device

Session Options

Option	Type	Default	Description
`clientId` Required	`String`	`undefined`	The `clientId` for your application. To get a client ID you need to register an application on the ArcGIS Developers website.
`clientSecret`	`String`	`undefined`	The `clientSecret` for this application. If set, this session will be authenticated as your application with full permissions.
`persistSession`	`Boolean`	`true`	If `true` Geotrigger JS will persist this session to a cookie or localStorage depending on browser capabilities.
`preferLocalStorage`	`Boolean`	`true`	If `true` the browser will prefer to use localStorage over cookies if available.
`automaticRegistation`	`Boolean`	`true`	If `true` and there is no `refreshToken` or `clientSecret` passed a new device will be registered and used for this session.
`refreshToken`	`String`	`undefined`	This should be the refresh token for the device. It will be used to get a new token if the original `token` is expired or not passed.
`token`	`String`	`undefined`	When authenticating as an existing device this can be set as a valid token for the device. If this is invalid the `refreshToken` will be used to get a new token.
`expiresOn`	`Date`	`undefined`	The expiration date for `token`. Used to help determine if the `token` is valid.
`proxy`	`String`	`undefined`	If you are using a proxy for IE 8 and 9 support this should be the path to your proxy. See browser support for more information.

Session Methods

Session.request(method, params, callback)

This is the primary method for interacting with the Geotrigger Service. It accepts a method the corresponds with the method you would like to call on teh Geotrigger API. an optional object of parameters and finally a callback function.

Before you can use request you will need a valid Geotrigger.Session object.

var geotriggers = new Geotrigger.Session({
  clientId: "ABC",
  clientSecret: "XZY"
});

Now that you have a session you can use the request method.

// list all triggers tagged "portland"
geotriggers.request("trigger/list", {
  tags: ["portland"]
}, function(error, response, xhr){
  console.log(error, response, xhr);
});

// if you dont need to pass parameters you can omit the "parameters" object
geotriggers.request("trigger/list", function(error, response, xhr){
  console.log(error, response, xhr);
});

// create a trigger
geotriggers.request("trigger/create", {
  condition: {
    direction: "enter",
    geo: {
      latitude: 45.5165,
      longitude: -122.6764,
      distance: 240
    }
  },
  action: {
    notification: {
      text: "Welcome to Portland"
    }
  }
},function(error, response, xhr){
  console.log(error, response, xhr);
});

Session.authenticated()

This function will check if a user is authenticated and has a token. It should be noted that this may return false in some cases (like the sample code below) as Geotrigger JS is still getting a token.

var geotriggers = new Geotrigger.Session({
  clientId: "ABC",
  clientSecret: "XZY"
});

// technically geotriggers is still getting a valid token so it's not authenticated

geotriggers.authenticated() // false

If you want to run a function as soon as a Session is authenticated you can use the Session.queue method or listen to the authentication:success and authentication:restored events.

Session.queue(callback)

Accepts a function to be called after authentication has succeeded or a session has been restored from localStorage or cookies. Can be called multiple times.

// create a new session by automatically registering a new device
var geotriggers = new Geotrigger.Session({
  clientId: "ABC"
});

// add an item to be called as soon as we have a new device
geotriggers.queue(function(){
  console.log(geotriggers.deviceId);
});

Session.refresh()

Manually refresh the session and persist it to a cookie or localStorage if applicable. This is used internally and generally you will not have to call this method.

Session.persist()

Persist it to a cookie or localStorage. This is used internally and generally you will not have to call this method.

Session.destroy()

This will destory the cookie or localStorage item essentially logging the user out and destorying the token.

Session.on(event, callback)

Used to listen to events on the session.

// create a new session by automatically registering a new device
var geotriggers = new Geotrigger.Session({
  clientId: "ABC"
});

// this will be called every time geotriggers gets new credentials
geotriggers.on("authentication:success", function(){
  console.log(geotriggers.deviceId);
});

Session.off(event, callback)

Remove bound events on the session.

// this would remove the event we added above
geotriggers.on("authentication:success", function(){
  console.log(geotriggers.deviceId);
});

Session Properties

Property	Description
`authenticatedAs`	Returns the type of authentication, either `application` if a `clientSecret` was passed or `device` if the sesson is for a device.
`deviceId`	If the session is authenticated as a device this will be that device's ID.
`key`	The unique key for persisting the session. Will generally looks like `geotriggers{{device
`refreshToken`	If the session is authenticated as a device this be the current refresh token.
`token`	The token for this session.

Session Events

Event Name	Description
`authentication:success`	Fired when Geotrigger JS has successfully authenticated as a device or application.
`authentication:restored`	Fired when Geotrigger JS has successfully restored a previous session from localStorage or cookies.
`authentication:error`	Fired when something went wrong with authenticaing or reauthenticing.

Persisting Authentication

Geotrigger JS will attempt to keep a session persisted for you. When you create a new Session it will check to see is a session already exists for the passed clientId in a cookie or in localStorage. If a session does exist, Geotrigger JS will use that session.

To disable this behavior set persistSession to false.

By default Geotrigger JS will try to store the session in localStorage. If you would prefer to use cookies to store your session set preferLocalStorage to false.

Expiring Tokens

Geotrigger JS will handle when your token expires and automatically get a new token for you and rerun your request. You can listen to the authentication:success and authentication:error events to know when Geotrigger JS is requesting new authentication.

Browser Support

Geotrigger.js supports any browser that supports CORS. IE 8 and 9 are supported but requires the use a proxy to work around limitations with XDomainRequest.

A Node.js proxy is supplied in the proxy folder. To create your own proxy to support IE 8 and 9 you can use that proxy as a sample implementation. Your proxy will need to forward POST requests like /proxy/http://geotrigger.arcgis.com/trigger/list to http://geotrigger.arcgis.com/trigger/list with all headers intact.

Limited testing has shown that our resource-proxies can be configured to do this successfully.

Development Instructions

Fork and clone Geotrigger JS
cd into the geotrigger-js folder
Install dependencies with npm install
Run tests with npm test or grunt test
- first cp spec/config.js.example spec/config.js and add valid clientId & clientSecret
Make your changes and create a pull request

Resources

ArcGIS for Developers
ArcGIS Geotrigger Service
@esripdx

Issues

Find a bug or want to request a new feature? Please let us know by submitting an issue.

Contributing

Esri welcomes contributions from anyone and everyone. Please see our guidelines for contributing.

Licensing

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

A copy of the license is available in the repository's license.txt file.

[](Esri Tags: Geotrigger) [](Esri Language: JavaScript)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

geotrigger.js

Features

Examples

As an application with `clientId` and `clientSecret`

As an existing device

As a new device

Documentation

Geotrigger.Session(options)

Session Options

Session Methods

Session.request(method, params, callback)

Session.authenticated()

Session.queue(callback)

Session.refresh()

Session.persist()

Session.destroy()

Session.on(event, callback)

Session.off(event, callback)

Session Properties

Session Events

Persisting Authentication

Expiring Tokens

Browser Support

Development Instructions

Resources

Issues

Contributing

Licensing

Files

README.md

Latest commit

History

README.md

File metadata and controls

geotrigger.js

Features

Examples

As an application with clientId and clientSecret

As an existing device

As a new device

Documentation

Geotrigger.Session(options)

Session Options

Session Methods

Session.request(method, params, callback)

Session.authenticated()

Session.queue(callback)

Session.refresh()

Session.persist()

Session.destroy()

Session.on(event, callback)

Session.off(event, callback)

Session Properties

Session Events

Persisting Authentication

Expiring Tokens

Browser Support

Development Instructions

Resources

Issues

Contributing

Licensing

As an application with `clientId` and `clientSecret`