@accedo/accedo-one 中文文档教程
Accedo One SDK for Node.js and browsers
_ _ ___
/_\ ___ ___ ___ __| | ___ /___\_ __ ___
//_\\ / __/ __/ _ \/ _` |/ _ \ // // '_ \ / _ \
/ _ \ (_| (_| __/ (_| | (_) | / \_//| | | | __/
\_/ \_/\___\___\___|\__,_|\___/ \___/ |_| |_|\___|
Summary
这是用于 Node.js 和浏览器的官方 Accedo One SDK,以前称为 AppGrid JS SDK。 虽然 Accedo One 公开了一组友好的 REST API,但此 SDK 旨在提供更流畅的 JS 编码体验。 它还鼓励使用最佳实践(例如:为客户端重复使用相同的 sessionId,但为不同的设备重复使用不同的客户端)。
我们遵循语义版本控制。 查看更改日志,了解每个版本的更改和新功能列表。
Supported browsers
这个项目是用 ES2015 编写的,浏览器构建被转换为 ES5。 支持所有现代浏览器(Firefox、Chrome、Opera、Safari、Edge,它们的移动版本和偏斜)。
⚠️ 如果您需要支持 IE 11(或其他旧版浏览器),请确保在加载此库之前加载 ES2015 功能的 polyfill。 您可以使用 babel 提供的一种,也可以只使用严格必要的:ES6 Promise polyfill 和 Object.assign
的另一种。 有关使用此类 polyfill 的示例,请参阅 example-browser.html
。
我们使用 CommonJS 模块而不是 ES6 模块,因此在 Node.js 上不需要编译步骤。
Supported Node.js versions
这应该从版本 4 开始工作,但我们测试并建议使用最新的 LTS 版本的 Node(目前是 Node 6,很快是 Node 8)。
Features
此 SDK 公开的默认工厂允许创建绑定到设备 ID 和应用程序密钥的客户端实例。 它提供了以下功能::
- 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 previous one has expired (lazy)
- ensures only one session will be created at a time, even if concurrent Accedo One requests are made
- specific to Detect:
- ensures concurrent calls to get the log level will result in one network call at most
- caches the log level for 3 minutes
- on browsers, individual logs are only sent when necessary (i.e. when the log's level is equal or higher than the current level set on the app), and automatically grouped then sent as a batch (see the
sendLog
doc)
信息源:_对于 Node,express 兼容的中间件也可以作为单独的包使用< /a>。 如果可能的话,你真的应该考虑使用它,因为它使事情变得更容易并提供额外的功能
Documentation
。_参考 此 SDK 的 API 文档。
您可能还想参考此 SDK 在幕后使用的 Accedo One Rest API 文档。 那里定义了 Accedo One 特定的术语。
Installation
npm install --save @accedo/accedo-one
(或者,对于 yarn 用户:yarn add @accedo/accedo-one
)
然后你可以使用默认导出来获取工厂:
const accedoOne = require('@accedo/accedo-one')
或者,使用 ES6 模块语法:
import accedoOne from '@accedo/accedo-one'
Examples
下面是一些示例,请参考 example-node.js
了解更多您可以自己运行的示例(克隆此 repo 然后执行 node example-node.js
).
Create an Accedo One client instance
:point_right: _在 Node 上,我们建议您改用 Express 中间件,因为它更容易并实施更多最佳实践
。必须获得 Accedo One 客户端的一个实例。 它是使用导出为该库中默认导出的工厂创建的,带有您需要的特定客户端的参数。
// This is an Accedo One client factory - name it "factory", "accedoOne", or anything else.
// If you use this library on a browser through a <script> tag, `accedoOne` is a global variable
// so you do not need to import or require anything.
import accedoOne from '@accedo/accedo-one';
const client = accedoOne({
appKey: 'YOUR_ACCEDO_ONE_APPLICATION_KEY',
deviceId: 'A_DEVICE_ID',
// if there is already a session for this appKey/deviceId tuple, provide it
sessionKey: 'AN_EXISTING_SESSION_KEY',
// gid can be passed as well, it will be used for all API calls
gid: 'SOME_GROUP_ID',
// turn on the SDK debug logs by adding a log function such as this one
// log(...args) { console.log(...args); },
});
您应该为每个需要访问 Accedo One API 的设备创建一个新客户端。
:warning: 不要 在你的 Node 服务器中重复使用一个客户端来转发来自不同消费者的请求。
如果您触发某些 Accedo One API 调用以响应服务器请求,您应该每次都创建一个新客户端,方法是使用工厂并重复使用您的应用程序密钥和消费者的设备 ID(通常您会保留一个通过 cookie 的消费者 deviceId,或作为服务器 API 中的请求参数 - 除非设备允许您使用一些唯一的 ID,如 MAC 地址)。
:bulb: 再次注意,中间件(见上文)为您完成这项工作,因此最好尽可能使用它。
Create a new Accedo One session
client.createSession
允许您手动创建一个新会话,该会话将被存储以供在此客户端实例上重复使用。 由于任何需要会话的 API 调用都会在需要时隐式触发此方法,您通常不需要自己执行此操作。
Get all Accedo One Metadata associated with your application key
client.getAllMetadata()
.then(metadata => {
console.log('Successfully requested all metadata from Accedo One', metadata);
})
.catch(error => {
// TODO handle error
});
SDK development
- Clone/fork this repo
- Run
yarn
(you should have yarn installed globally) - Code !
- Before pushing, remember to:
- update the UMD bundle (
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
)
- update the UMD bundle (
Testing code in the browser
如有必要,如上所述更新 UMD 包,然后在浏览器中打开 example-browser.html
文件。
在 OSX shell 上,您可以使用 open example-browser.html
。 要在本地 Web 服务器上提供它,您可以使用 php -S localhost:9000
或 python -m SimpleHTTPServer 9000
如果您的路径上有可用的 php 或 python 二进制文件。 其他选项包括 Apache、Nginx 和基于节点的服务器,例如 http-server
或 static-server
。
该示例包括旧浏览器(如 IE11(不支持 ES6 的浏览器))所需的 polyfill。
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 单元测试以涵盖从该模块导出的所有 API。 我们将通过运行 npm test
或 yarn test
调用测试。
License
请参阅许可文件以了解许可权利和限制 (Apache 2.0)
Accedo One SDK for Node.js and browsers
_ _ ___
/_\ ___ ___ ___ __| | ___ /___\_ __ ___
//_\\ / __/ __/ _ \/ _` |/ _ \ // // '_ \ / _ \
/ _ \ (_| (_| __/ (_| | (_) | / \_//| | | | __/
\_/ \_/\___\___\___|\__,_|\___/ \___/ |_| |_|\___|
Summary
This is the official Accedo One SDK for Node.js and browsers, previously known as the AppGrid JS SDK. 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 for a listing of changes and new features per version.
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.
We use CommonJS modules rather than ES6 modules, so no compilation step is needed on Node.
Supported Node.js versions
This should work from version 4, but we test on, and recommend to use the latest LTS version of Node (currently Node 6, soon Node 8).
Features
The default factory exposed by this SDK allows creating a client instance tied to a device id and an application key. It provides these features :
- 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 previous one has expired (lazy)
- ensures only one session will be created at a time, even if concurrent Accedo One requests are made
- specific to Detect:
- ensures concurrent calls to get the log level will result in one network call at most
- caches the log level for 3 minutes
- on browsers, individual logs are only sent when necessary (i.e. when the log's level is equal or higher than the current level set on the app), and automatically grouped then sent as a batch (see the
sendLog
doc)
:information_source: _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 @accedo/accedo-one
(or, for yarn users: yarn add @accedo/accedo-one
)
Then you can use the default export to get a factory:
const accedoOne = require('@accedo/accedo-one')
Or, using the ES6 module syntax:
import accedoOne from '@accedo/accedo-one'
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
:point_right: _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", "accedoOne", or anything else.
// If you use this library on a browser through a <script> tag, `accedoOne` is a global variable
// so you do not need to import or require anything.
import accedoOne from '@accedo/accedo-one';
const client = accedoOne({
appKey: 'YOUR_ACCEDO_ONE_APPLICATION_KEY',
deviceId: 'A_DEVICE_ID',
// if there is already a session for this appKey/deviceId tuple, provide it
sessionKey: 'AN_EXISTING_SESSION_KEY',
// gid can be passed as well, it will be used for all API calls
gid: 'SOME_GROUP_ID',
// turn on the SDK debug logs by adding a log function such as this one
// log(...args) { console.log(...args); },
});
You should create a new client for every device that needs to access the Accedo One APIs.
:warning: 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).
:bulb: Note again, the middleware (see above) does that work for you, so it's best to use it whenever possible.
Create a new Accedo One session
The client.createSession
lets you manually create a new session, that will be stored for reuse onto this client instance. As any API call that needs a session will trigger this method implicitly when needed, you will normally not need to ever do this yourself.
Get all Accedo One Metadata associated with your application key
client.getAllMetadata()
.then(metadata => {
console.log('Successfully requested all metadata from Accedo One', metadata);
})
.catch(error => {
// TODO handle error
});
SDK development
- Clone/fork this repo
- Run
yarn
(you should have yarn installed globally) - Code !
- Before pushing, remember to:
- update the UMD bundle (
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
)
- update the UMD bundle (
Testing code in the browser
If necessary, update the UMD bundle as noted 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 like IE11 (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)