EVRYTHNG Client Javascript SDK
evrythng.js is a Javascript library that facilitates the interaction with the EVRYTHNG REST API thanks to its fluent API. It helps EVRYTHNG Application developers to build client apps faster and easier.
evrythng.js can be used both in Web applications (Browser) and embedded/server applications using Node.js. The difference being the transport layer - Browser's XHR vs Node's HTTP.
evrythng.js is intended to be used with EVRYTHNG Applications and corresponding Application Users or with Devices. Be sure to only include your EVRYTHNG Application API key and not your Operator, User or Device key in any public source code (read more about Scope Permissions).
See Related Tools below for other usages.
With Bower
bower install evrythng --save
The Bower package is AMD-compatible. This means you can load it asynchronously using tools like Require.js or simply dropping the script tag into your HTML page:
<script src="bower_components/evrythng/dist/evrythng.js"></script>
See Usage below for more details.
Add the script tag into your HTML page:
<script src="//cdn.evrythng.com/toolkit/evrythng-js-sdk/evrythng-4.7.2.min.js"></script>
Or always get the latest release (warning, new releases might break your code!):
<script src="//cdn.evrythng.com/toolkit/evrythng-js-sdk/evrythng.js"></script>
<script src="//cdn.evrythng.com/toolkit/evrythng-js-sdk/evrythng.min.js"></script>
For HTTPS you need to use:
<script src="//d10ka0m22z5ju5.cloudfront.net/toolkit/evrythng-js-sdk/evrythng-4.7.2.min.js"></script>
<script src="//d10ka0m22z5ju5.cloudfront.net/toolkit/evrythng-js-sdk/evrythng.js"></script>
<script src="//d10ka0m22z5ju5.cloudfront.net/toolkit/evrythng-js-sdk/evrythng.min.js"></script>
npm install evrythng --save
For advanced usage and options, see Documentation below.
requirejs.config({
paths: {
evrythng: '../bower_components/evrythng/dist/evrythng'
}
});
require(['evrythng'], function (EVT) {
var app = new EVT.App(APP_API_KEY);
...
});Create a new scope object of the required actor type to begin making API requests with it:
var EVT = require('evrythng');
var app = new EVT.App(APP_API_KEY);
...The scope can be used immediately to make other API calls (that do not require information about the scope beyond the API key used to construct it):
var app = new EVT.App(APP_API_KEY);
// Read all products
app.product().read().then(console.log);However, if information about the scope itself (such as the application ID for
an EVT.App scope, for example) is required as soon as possible, use the
returned promise to be notified when the scope is ready for use.
Note: This applies to all scopes (including EVT.Operator,
EVT.TrustedApp, EVT.User, and EVT.Device).
Below is an example of this mode of usage:
var app = new EVT.App(APP_API_KEY);
app.$init.then((app) => {
// The scope 'id' property is now ready for use
console.log(app.id);
});If you aren't using any of the above script loading mechanisms, the EVT module is available
as a global (EVT):
var app = new EVT.App(APP_API_KEY);
...Setup global settings (see all options):
EVT.setup({
apiUrl: 'https://api.evrythng.com'
});Access resources using the Promise API:
app.product('57bad69fc18104025b292da8').read().then(function(product) {
console.log(product);
});Update single product property:
product.property('status').update('off');Update multiple properties:
product.property().update({
status: 'off',
level: '80'
});Read current property:
console.log(product.properties['status']);Read property history:
product.property('status').read().then(function(statusHistory) {
console.log(statusHistory);
});Login an existing user (with Evrythng Auth) and create user scope:
app.login({
email: 'myemail',
password: 'mypass'
}).then(function(response) {
// every call using user will use its User Api Key
var user = response.user;
});Log the user out:
user.logout();Create a Thng:
user.thng().create({
name: 'name',
description: 'desc'
});Read all thngs and update first Thng's description:
user.thng().read().then(function(thngs) {
thngs[0].description = 'newDesc';
return thngs[0].update();
}).then(function(thng) {
console.log('thng 0 updated');
});Update existing Thng:
user.thng('123').update({
description: 'new desc'
});#### Actions
Create a new action:
// Actions request device geolocation by default (if available)
// Use 'geolocation: false' option globally or per request to turn it off
thng.action('scans').create();Create a custom action:
thng.action('_customAction').create({
customFields: {
foo: 'bar'
}
});### Using request options
app.product().read({
fullResponse: true,
params: {
perPage: 100,
project: '123',
context: true // actions only
...
},
headers: {
authorization: 'anotherApiKey',
accepts: 'image/png'
}
}).then(function(result) {
// Using fullResponse, result contains 'data', 'headers' and 'status'
console.log(result.headers['x-result-count'] + ' Products:', result.data);
});### Using filters
Specify filter params to limit the returned results to matched criteria:
app.product().read({
params: {
filter: 'name=My Product&tags=shipped' // regular parameter string notation
}
});
app.product().read({
params: {
filter: {
name: 'My Product', // object notation
tags: 'shipped'
}
}
});### Facebook login
In order to use FB login, the application needs to be initialized with facebook property having truthy value:
app = new EVT.App({
apiKey: APP_API_KEY,
facebook: true
});
app.login('facebook').then(function(response) {
var user = response.user;
console.log(app.socialNetworks.facebook.appId);
user.logout('facebook');
});It's possible to pass custom configuration to FB.init via faceboook config property:
app = new EVT.App({
apiKey: APP_API_KEY,
facebook: {
version: 'v2.8'
cookie: false,
fbml: true
}
});For more options see the method reference.
Create and validate a new app user:
app.appUser().create({
email: 'someone@anyone.com',
password: 'password', // don't put this one in the code :)
firstName: 'Some',
lastName: 'One'
}).then(function(appUser) {
console.log('Created user: ', appUser);
// validate app user
return appUser.validate();
}).then(function(appUser) {
// validated user and his api key
console.log('Validated app user: ', appUser);
});Track a device without creating a full app user:
// Create anonymous user
app.appUser().create({
anonymous: true
}).then(function(anonymousUser) {
console.log('Created anonymous user: ', anonymousUser); // good to go, doesn't need validation
// store anonymous user details locally
if (window.localStorage) {
localStorage['userId'] = anonymousUser.id;
localStorage['apiKey'] = anonymousUser.apiKey;
}
});Restore a user from saved details:
var anonymousUser = new EVT.User({
id: localStorage['userId'],
apiKey: localStorage['apiKey']
}, app);As a Device
Create a Device scope to manage a Thng and allow it to update itself:
var device = new EVT.Device({
apiKey: DEVICE_API_KEY,
id: 'thngId'
});
// update the related thng
device.update({
customFields: {
foo: 'bar'
}
}).then(function(updated) {
console.log('updated device details: ', updated);
});
// CRUD properties
device.property('temperature').update(32);
device.property('humidity').read().then(function(results) {
console.log('humidity readings:', results);
});
// CR actions
device.action('_turnOn').create();The Iterator API is an Async Generator Function added to each Resource.
// Initialize app using appApiKey
var app = new EVT.App('APP_API_KEY');
var it = app.product().iterator();
// .next() returns a promise with the next generator value (page value from API).
// result.done denotes when the iterator reached the end.
// Get page by page
it.next().then(function(result){
console.log(result.value);
return it.next();
}).then(result){
console.log(result.value);
console.log(result.done);
});
// The iterator can be initialized with the same options as any CRUD request.
// This will iterate through all the Products in the Application's project scope,
// that are tagged with 'test', with the result in ascending order and in chunks of 100
var it = app.product().iterator({
params: {
perPage: 100,
sortOrder: 'ASCENDING',
filter: {
tags: 'test'
}
}
});
it.next().then(function(result){
console.log(result.value);
});
// In order to easily loop through all the items, we provide a utility function
// that asynchronously iterates through all the generated pages in order, until
// there are no more results
EVT.Utils.forEachAsync(it, function(val){
val.forEach(function(product){
console.log(product.name);
});
});Generator functions and the yield
keyword arrived with great excitement in Node v0.11.2 and the latest evergreen browsers.
This allows people targeting these platforms to write asynchrounous code that looks synchronous. ES7 Async Functions will give you a quick introduction.
function *apiCalls(){
try{
// Yield promise to thngs (i.e. wait for it to resolve/reject)
var thngs = yield user.thng().read();
console.log(thngs.length);
// Yield promise to thng properties
var properties = yield thngs[0].property().read();
console.info(properties);
} catch(e){
// Will catch every rejected request as well as exceptions
console.info('Caught: ', e);
}
}
// Iterate through generator
EVT.Utils.spawn(apiCalls());The EVRYTHNG API has evrythng.js examples whenever applicable. If you'd like to see what's going on under the hood, check out the Annotated Source.
Source Maps are available, which means that when using the minified version, if you open Developer Tools (Chrome, Safari, Firefox), .map files will be downloaded to help you debug code using the original uncompressed version of the library.
evrythng-extended.js is an extended version of evrythng.js which
includes Operator access to the API.
evrythng-scan.js is an evrythng.js plugin that lets you identify
Products and Thngs right from your browser, without using a standalone QR Code scanning app. It also supports
Image Recognition.
evrythng-mqtt is an evrythng.js plugin for Node.js that adds support
for real-time MQTT methods to any resource.
evrythng-hub is an evrythng.js plugin for both Browser and Node.js that
adds smart routing of local requests when in the context of a Thng-Hub Gateway.
Apache 2.0 License, check LICENSE.txt
Copyright (c) EVRYTHNG Ltd.