Accedo One SDK for Node.js and browsers
_ _ ___
/_\ ___ ___ ___ __| | ___ /___\_ __ ___
//_\\ / __/ __/ _ \/ _` |/ _ \ // // '_ \ / _ \
/ _ \ (_| (_| __/ (_| | (_) | / \_//| | | | __/
\_/ \_/\___\___\___|\__,_|\___/ \___/ |_| |_|\___|
Summary
This is the official Accedo One SDK for Node.js and browsers. While Accedo One exposes a set of friendly REST APIs, this SDK is intended to provide a smoother experience when coding in JS. It also encourages the use of best practices (for example: reusing the same sessionId for a client, but different clients for different devices).
We follow semantic versioning. Check the change log to find out what changed between versions.
Supported browsers
This project is written in ES2015 and the browsers build is transpiled to ES5. All modern browsers are supported (Firefox, Chrome, Opera, Safari, Edge, their mobile versions and declinations).
⚠️ If you need to support IE 11 (or other legacy browsers), make sure to load polyfills for the ES2015 features before loading this library. You can either use one such as what babel offers, or just the strict necessary: an ES6 Promise polyfill and another one for Object.assign
.
Refer to example-browser.html
for an example on using such a polyfill.
Supported Node.js versions
This should work from version 4, but we test on, and recommend to use Node LTS version 6 or above.
Features
These features are provided by the manual creation of Accedo One client instances (via the default exported factory) :
- easy access to Accedo One APIs
- automatic deviceId creation when none was provided
- automatic session creation when none was provided (lazy - only when needed)
- automatic session re-creation when the existing one has expired (lazy)
- ensures only one session will be created at a time, even if a request triggers concurrent Accedo One calls
- specific to Detect:
- ensures concurrent calls to get the log level will result in one network call at most
- anytime the log level is obtained, it is cached for the next 3 minutes
- on the browser, individual logs are not sent when not necessary (i.e. when the log's level is lower than the current level set on the app)
ℹ️ For Node, an express-compatible middleware is also available as a separate package. You should really consider using it if possible, as it makes things even easier and provides extra features.
Documentation
Refer to the API docs for this SDK.
You may also want to refer to the Accedo One Rest API documentation that this SDK uses behind the scenes. Accedo One-specific terminology is defined there.
Installation
npm install --save appgrid
(or, for yarn users: yarn add appgrid
)
Then you can use the default export to get a factory:
const appgrid =
Or, using the ES6 module syntax:
Examples
Below are a few examples, refer to example-node.js
for more of them that you can run yourself (clone this repo then execute node example-node.js
).
Create an Accedo One client instance
👉 On Node, we recommend you use the Express middleware instead, as it makes it easier and enforces some more best practices.
An instance of an Accedo One client must be obtained. It's created with the factory exported as the default export in this library, with parameters for the specific client you need.
// this is an Accedo One client factory - name it "factory", "appgrid" (as above), or anything else; const client = ;
You should create a new client for every device that needs to access the Accedo One APIs.
⚠️ DO NOT reuse a single client, in your Node server, to relay requests from various consumers.
If you are triggering some Accedo One API calls in response to server requests, you should create a new client every time, by using the factory and reusing your application key and the consumer's deviceId (typically you would persist a consumer deviceId via the cookies, or as a request parameter in your server APIs - unless the device lets you use some unique ID like a MAC address).
💡 Note again, the middleware (see above) does that work for you, so it's best to use it whenever possible.
Get a new Accedo One SessionId
This lets you manually create a new session, that will be stored for reuse onto this client instance. Note that any API call that needs a session will trigger this method implicitly if no session is attached to the client yet.
client ;
Get all Accedo One Metadata associated with your AppId
client ;
SDK development
- Clone/fork this repo
- Run
yarn
(you should have yarn installed globally) - Develop !
- Before pushing, remember to:
- generate updated UMD and ES6 bundles (
yarn run build
) - add tests and check they all pass (
yarn test
) - add examples and check they all work (
node example-node.js
) - document any public API with JSDoc comments and generate the new doc (
yarn run doc
)
- generate updated UMD and ES6 bundles (
Testing code in the browser
Make sure to build as mentioned above, then open the example-browser.html
file in your browser.
On an OSX shell, you can use open example-browser.html
.
To serve it on a local web server, you can use php -S localhost:9000
or python -m SimpleHTTPServer 9000
if you have php or python binaries available on your path.
Other options include Apache, Nginx, and Node-based servers such as http-server
or static-server
.
The sample includes the polyfills necessary for older browsers (those that do not support ES6).
More information & Links
- Accedo One homepage
- Accedo One help center
- Accedo One API documentation
- The Express-compatible middleware that relies on this library.
Unit Tests
Jest unit tests have been written to cover all of the exported APIs from this module. Tests will we called by running npm test
or yarn test
.
License
See the LICENSE file for license rights and limitations (Apache 2.0)