Navigation

Attach a device

Links a device to a user. Call this function in all key views in your project. See when to call the attach function for details.

Parameters

Client ID REQUIRED

The string client ID of your project's API key.

User REQUIRED

The ID of the user you want the device to be linked to. This can be the ID of the user in your own DB, or a custom generated user ID specifically for Sabil. Regardless, this ID must be saved in your DB and unique to each user.

Secret

The signed token for this user. Use this if and only if you are following the advanced security guide.

  • Default: undefined

Suspended URL

The URL to redirect the user to if their account is suspended. If no URL is provided and the user is suspended, the user will be redirected to a page hosted by Sabil. The hosted page includes your projects branding and can be customized on the dashboard.

  • Default: undefined

Identity

The Identity id returned from the sabil-identity library.

  • Default: undefined

Metadata

A key-value object that will be stored. This is useful if you want to store additional data. This will be available in all webhooks touching this object.

  • Default: undefined

Debug

A boolean indicating whether to run in debug mode or not. If debug is true, any errors will be printed to the console as well as warnings and recommendations.

  • Default: false

Language

An object with the language params to use when displaying the blocking dialog. See details here. If left undefined, defaults to English.

  • Default: undefined

RTL

A boolean indicating whether to display the blocking dialog in a right to left view. See details here.

  • Default: false

Show Blocking Dialog

A boolean that controls (and overrides) settings to display the dialog. This value will only ever be looked at if the user exceeds the device limit. If you intend to control the blocking dialog from the dashboard, you must leave this value blank (i.e. don't pass anything for it, or pass null).

  • Default: undefined

Limit Config

An object that allows you to override the settings of the project default limits. This can be useful if you want to set the limit for each individual user depending on his or her plan. It supports multiple properties, but the only one that is currently active is: limit_config.overall_limit which controls the overall device limit and does not differentiate between mobile and desktop. Leave this undefined if you want to rely on the dashboard configuration. If the blocking dialog is not enabled, this value is ignored.

  • Default: {} (empty object)

Appearance Config

An object to control the appearance of the blocking dialog. If the blocking dialog is not enabled, this value is ignored. You can pass two properties on the JS SDKL

  1. dark: true/false
  2. font_family: a css style to add to all texts displayed on the dialog. It is highly recommended that you set these two values to match your site's appearance. On the iOS and Android SDKs, only the dark property is available.
  • Default: {} (empty object)

On Current Device Logout

A function that's called whenever the current device needs to be detached. This can happen in one of two scenarios:

  1. The user was shown the dialog and select to log out of this device. Keep in mind, the user could be asking to log out this device from another device where the dialog is presented. Or they can select to log out of the same device. In both cases, the function is called.
  2. You manually call detach and passed the device ID of a specific device. If the device with that ID implements this callback and it's online, it will be immediately called.

It is strongly recommended that you implement this callback. Inside this callback, you should immediately log the user out of your application.

  • Default: undefined

On Limit Exceeded

A function that's called when the user exceeds the specified device limit. For details on limits, see the Configuring device limits guide. A single parameter is passed to this function: an object containing the device count attached_devices

On Other Device Logout

A function that's called if and only if the user is shown the blocking dialog, and selects to log out another device. This function takes one parameter which is the device details that was selected to log out. You should avoid calling detach here because it will already be invoked by the SDK. Use this only for your internal purposes and nothing else. It is perfectly safe to ignore this callback.

  • Default: undefined

Returns

This function returns a UserAccessState object.


SDK Syntax

const { device_id } = await Sabil.attach({  client_id: `client_id`,  show_blocking_dialog: false,  user: `user_id`,  debug: true,  appearance_config: {    font_family: `Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu,    Cantarell, 'Fira Sans', 'Droid Sans', 'Helvetica Neue', sans-serif`,    dark: false,  },  on_current_device_logout() {    alert("This device has been logged out");  },});