geotrigger-js

Small client for interacting with the ArcGIS Geotrigger Service.

geotrigger.js

An API client for the ArcGIS Geotrigger Service.

  1. Features
  2. Examples
  1. Documentation
  2. Geotrigger.Session(options)
* [Options](#session-options)
* [Methods](#session-methods)
* [Properties](#session-properties)
* [Events](#session-events)
* [Persisting Authentication](#persisting-authentication)
* [Expiring Tokens](#expiring-tokens)
  1. Browser Support and Proxies
  2. Development Instructions
  3. Resources
  4. Issues
  5. Contributing
  6. Licensing
  • CORS support
  • No dependencies
  • Handles authentication, persisting and refreshing sessions
  • Works in browsers and in Node.js

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(errorresponsexhr){
  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.

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(errorresponsexhr){
  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.

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(errorresponsexhr){
  console.log(error, response, xhr);
});

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.

OptionTypeDefaultDescription
clientId RequiredStringThe clientId for your application. To get a client ID you need to register an application on the ArcGIS Developers website.
clientSecretStringThe clientSecret for this application. If set, this session will be authenticated as your application with full permissions.
persistSessionBooleantrueIf true Geotrigger JS will persist this session to a cookie or localStorage depending on browser capabilities.
preferLocalStorageBooleantrueIf true the browser will prefer to use localStorage over cookies if available.
automaticRegistationBooleantrueIf true and there is no refreshToken or clientSecret passed a new device will be registered and used for this session.
refreshTokenStringThis 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.
tokenStringWhen 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.
expiresOnDateThe expiration date for token. Used to help determine if the token is valid.
proxyStringIf 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.

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(errorresponsexhr){
  console.log(error, response, xhr);
});
// if you dont need to pass parameters you can omit the "parameters" object 
geotriggers.request("trigger/list", function(errorresponsexhr){
  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(errorresponsexhr){
  console.log(error, response, xhr);
});

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.

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);
});

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.

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

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

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);
});

Remove bound events on the session.

// this would remove the event we added above 
geotriggers.on("authentication:success", function(){
  console.log(geotriggers.deviceId);
});
PropertyDescription
authenticatedAsReturns the type of authentication, either application if a clientSecret was passed or device if the sesson is for a device.
deviceIdIf the session is authenticated as a device this will be that device's ID.
keyThe unique key for persisting the session. Will generally looks like `geotriggers{{deviceapplication}}_{{clientId}}`.
refreshTokenIf the session is authenticated as a device this be the current refresh token.
tokenThe token for this session.
Event NameDescription
authentication:successFired when Geotrigger JS has successfully authenticated as a device or application.
authentication:restoredFired when Geotrigger JS has successfully restored a previous session from localStorage or cookies.
authentication:errorFired when something went wrong with authenticaing or reauthenticing.

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.

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.

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.

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

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

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

Copyright 2013 Esri

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)