ns-limp

官方 NativeScript Angular SDK for LIMP.

快速开始

当前 SDK 有两个依赖

• jsrasgin
• nativescript-websockets 这些依赖项应该会自动与库一起安装。

为 NativeScript 安装 ns-limp

tns plugin add ns-limp

如何使用

1. 在组件中使用

import { Component, OnInit } from '@angular/core';

import { ApiService, Res } from 'ns-limp/api.service';

@Component({
	selector: 'app-root',
	templateUrl: './app.component.html',
	styleUrls: ['./app.component.css']
})
export class AppComponent implements OnInit {

	constructor(private api: ApiService) {}

	ngOnInit() {
		this.api.init({
			api: 'ws://127.0.0.1:8081/ws',
			anonToken: '__ANON',
			authAttrs: ['email']
		});
	}
}

SDK 配置

初始化 SDK 时，您应该传递一个符合 SDKConfig 接口的对象，该对象具有以下属性

1. api（必需）：您要连接到的 LIMP 应用程序的 URI。
2. anonToken（必需）：LIMP 应用的 ANON_TOKEN。
3. authAttrs（必需）：从 LIMP APIv5.8 开始，LIMP 应用程序没有严格的 User 模块属性结构。这包括每个应用程序设置的认证属性。此属性表示一个指向应用程序相同认证属性的 Array<string>。
4. debug（可选）：一个表示 SDK 上调试模式状态的 Boolean。如果 true，您将在浏览器控制台看到关于传输和接收的消息的详细消息。默认 false。
5. fileChunkSize（可选）：一个表示作为将二进制数据推送到 LIMP 应用程序的过程的一部分上传的文件块大小的 Number（以字节为单位）。默认 512000。
6. authHashLevel（可选）：可以是 5.0 或 5.6。由于 LIMP APIv5.6 中引入的认证哈希生成更改，一些遗留应用程序由于哈希差异而无法升级到 APIv5.6 和更高版本。SDKv5.7 添加了 authHashLevel，以允许开发人员使用更高版本的 API 和 SDK 与遗留应用程序一起使用。默认 5.6；

最佳实践

您可以根据自己的开发风格完全使用 SDK，但我们有一些提示

会话重新认证

处理 reauth 场景的最佳实践是尽快尝试 checkAuth。这可以通过订阅 inited$ 主题来实现，该主题通知订阅有关 SDK 初始化状态的任何更改，这些更改反映为 SDK 中的 inited 属性。可以这样做

this.api.inited$.subscribe((init: boolean) => {
	if (init) {
		// SDK is inited and ready for your calls:
		try {
			// Wrap in try..catch to handle error thrown if no credentials cached
			this.api.checkAuth();
		} catch { }
	}
}, (err: Res<Doc>) => {
	console.log('inited$.err', err);
});

认证状态检测

虽然您可以在 auth、reauth 和 checkAuth 调用的订阅中检测用户认证状态，但最佳实践是使用全局的 authed$ 状态 Subject。您可以通过在启动 SDK 的相同组件（通常是 AppComponent）中订阅 authed$ 来做到这一点。这确保了作为 api.init 订阅的一部分可以成功处理 checkAuth。建议的模式是

this.api.authed$.subscribe((session: Doc) => {
	if (session) {
		console.log('We are having an `auth` condition with session:', session);
	} else {
		console.log('We just got unauthenticated');
	}
});

断开连接后重新连接

WebSocket 是始终活跃的连接。这里可能发生很多错误，从而导致与您的 LIMP 应用程序的连接。为了确保您始终可以重新连接，当 SDK 变得不再 inited 时，请再次调用 SDK 的 init 方法。

import { Component, OnInit } from '@angular/core';

import { ApiService, Res } from 'ns-limp/api.service';

@Component({
	selector: 'app-root',
	templateUrl: './app.component.html',
	styleUrls: ['./app.component.css']
})
export class AppComponent implements OnInit {

	constructor(private api: ApiService) {
		this.api.inited$.subscribe((init: boolean) => {
			if (init) {
				// SDK is inited and ready for your calls:
				try {
					// Wrap in try..catch to handle error thrown if no credentials cached
					this.api.checkAuth();
				} catch { }
			} else {
				// SDK just got not inited, let's init SDK again:
				this.init();
			}
		}, (err: Res<Doc>) => {
			console.log('inited$.err', err);
		});
	}

	ngOnInit() {
		this.init();
	}

	init(): void {
		this.api.init({
			api: 'ws://127.0.0.1:8081/ws',
			anonToken: '__ANON',
			authAttrs: ['email']
		});
	}
}

API 参考

debug

表示SDK上调试模式状态的布尔值。如果为true，您将在浏览器控制台中看到有关传输和接收的消息的详细消息。默认false。

fileChunkSize

表示在将二进制数据推送到LIMP应用的过程中上传的文件块大小的数字（以字节为单位）。默认512000。

session

表示当前会话的Doc对象。仅在用户认证时具有值。

authed

存储当前用户认证状态的布尔值。

authed$

可以订阅以处理用户认证状态变化的Subject<Boolean | Doc>。

init()

用于与LIMP应用建立连接的基本方法。如果出于任何原因需要读取API接收到的每条消息，则此方法返回一个Observable以进行链式订阅，但订阅它不是必需的。方法定义

init(api: String, anonToken: String): Observable<Res<Doc>> { /*...*/ }

close()

关闭与LIMP应用当前连接的方法。如果出于任何原因需要读取close调用的响应，则此方法返回一个Observable以进行链式订阅，但订阅它不是必需的。方法定义

close(): Observable<Res<Doc>> { /*...*/ }

auth()

可以使用此方法对用户进行认证。如果出于任何原因需要读取auth调用的响应，则此方法返回一个Observable以进行链式订阅，但订阅它不是必需的。方法定义

auth(authVar: string, authVal: string, password: string): Observable<Res<Doc>> { /*...*/ }

reauth()

可以使用此方法重新认证用户。如果没有从以前的成功的认证调用中缓存sid和token属性，则此方法会失败。此方法不应直接调用，而是使用checkAuth()。如果出于任何原因需要读取reauth调用的响应，则此方法返回一个Observable以进行链式订阅，但订阅它不是必需的。方法定义

reauth(sid: string = this.cache.get('sid'), token: string = this.cache.get('token')): Observable<Res<Doc>> { /*...*/ }

signout()

可以使用此方法注销当前用户。成功后，此方法将删除会话的所有缓存属性。如果出于任何原因需要读取signout调用的响应，则此方法返回一个Observable以进行链式订阅，但订阅它不是必需的。方法定义

signout(): Observable<Res<Doc>> { /*...*/ }

checkAuth()

检查是否存在缓存的会话并尝试重新认证用户的函数。如果没有缓存的凭据，则会抛出错误，因此您需要始终将其包裹在try..catch中。如果出于任何原因需要读取checkAuth调用的响应，则此方法返回一个Observable以进行链式订阅，但订阅它不是必需的。方法定义

checkAuth(): Observable<Res<Doc>> { /*...*/ }

generateAuthHash()

用于生成认证散列的方法。此方法用于auth()调用。但是，您还需要在创建用户时生成这些值。方法定义

generateAuthHash(authVar: string, authVal: string, password: string): string { /*...*/ }

deleteWatch()

删除正在进行的监视的方法。您可以传递要删除的监视ID，或者传递__all以删除所有监视。如果出于任何原因需要读取deleteWatch调用的响应，则此方法返回一个Observable以进行链式订阅，但订阅它不是必需的。方法定义

deleteWatch(watch: string | '__all'): Observable<Res<Doc>> { /*...*/ }

call()

SDK中最重要的方法。您使用此方法调用LIMP应用中的不同端点。尽管在params中的callArgs对象具有所有调用属性的完整定义，但您通常只需在大多数情况下传递query和/或doc。第三个参数awaitAuth指定调用是否应在会话认证后排队。方法定义

call(endpoint: string, callArgs: callArgs, awaitAuth: boolean = false): Observable<Res<Doc>> { /*...*/ }

贡献指南

感谢您对ns-limp感兴趣。

有关向此项目贡献的更多详细信息，请参阅贡献指南。