@amazon-devices/kepler-identifiers

Overview

@amazon-devices/kepler-identifiers provides Identifiers API support to Kepler. The module provides functionality for generating and retrieving and managing identifiers such as UUIds, device name and user agent and tracking/ad identifiers.

Getting Started

Installation

1. Add the JavaScript library dependency in the package.json file:

"dependencies": {
...
"@amazon-devices/kepler-identifiers": "~0.0.1"
}

2. Regenerate the package-lock.json file using the npm install command.

Common Use Cases

Generate UUID v4

import { KeplerIdentifiers as Identifiers } from '@amazon-devices/kepler-identifiers';

const handleGenerateUuidV4 = () => {
  try {
    let result = Identifiers.generateUuidV4()
    return result;
  }catch (error) {
    console.error(error);
  }
};

Set Friendly Device Name

import { KeplerIdentifiers as Identifiers } from '@amazon-devices/kepler-identifiers';

const handleSetFriendlyDeviceName = async () => {
  try {
    await Identifiers.setFriendlyDeviceName("newfriendlydevicename");
    console.log("New friendly device name set");
  } catch (error) {
    console.error("Failed to set friendly device name:", error);
  }
};

Get Friendly Device Name

The method getFriendlyDeviceName() gets the friendly name of this device for the current persona.

Returns one of:

• The user-customized device name if it exists and the caller has the "com.amazon.devconf.privilege.identifiers.device-friendly-name" run-time privilege
• The device model name if either:
  • No user-customized name has been set
  • The caller lacks the required privilege

import { KeplerIdentifiers as Identifiers } from '@amazon-devices/kepler-identifiers';

const handleGetFriendlyDeviceName = async () => {
  try {
    let result = await Identifiers.getFriendlyDeviceName();
    return result;
  }catch (error) {
    console.error(error);
  }
};

Requesting for the run-time privilege

Privilege can be acquired by getting the user consent. User consent dialogue can be initiated by requesting run-time privilege "com.amazon.devconf.privilege.identifiers.device-friendly-name" through Security Manager API "@amazon-devices/security-manager-lib".

import {SecurityManager, PrivilegeState} from '@amazon-devices/security-manager-lib';
import { KeplerIdentifiers as Identifiers } from '@amazon-devices/kepler-identifiers';

const DEVICE_NAME_PRIVILEGE = 'com.amazon.devconf.privilege.identifiers.device-friendly-name';
SecurityManager.getPrivilegeState(DEVICE_NAME_PRIVILEGE).then(
      function(state: PrivilegeState) {
        if (state == PrivilegeState.ALLOW) {
          // User had consented.
          return Identifiers.getFriendlyDeviceName();
        } else {
          // Request for user consent
          // This call blocks, each app will integrate this call into their threading model or event loop
          SecurityManager.requestPrivilege(DEVICE_NAME_PRIVILEGE).then(
            function(state: PrivilegeState) {
              if (state == PrivilegeState.ALLOW) {
                // User has consented now.
                return Identifiers.getFriendlyDeviceName();
              } else {
                // User didn't consent.
              }
            },
            function(error: Object) { KPLOG().error("Failed to request privilege: {}", error["message"]); }
          )
        }
      },
      function(error: Object) { KPLOG().error("Failed to get privilege state: {}", error["message"]); }
    )

Additionally add the following to application manifest.toml,

 [[needs.privilege]]
 id = "com.amazon.devconf.privilege.identifiers.device-friendly-name"

See Request Run-time Privileges and Security Manager API for more details.