initialize

Last updated on Aug 1, 2023

The initialize function creates an instance of the Beyond Identity SDK class Embedded, providing access to the rest of the SDK functions. The initialize function must be called first, before any other SDK functions.

Dependencies

The initialize function requires the Beyond Identity SDK.

JavaScript

yarn add @beyondidentity/bi-sdk-js

or

npm install @beyondidentity/bi-sdk-js

Kotlin

Gradle

To enable the retrieval of Cloudsmith hosted packages via Gradle, we need to add the Cloudsmith repository to the root/build.gradle file.

repositories {
    maven {
        url "https://packages.beyondidentity.com/public/bi-sdk-android/maven/"
    }
}

After the repository is added, we can specify the Beyond Identity dependencies.

dependencies {
    implementation 'com.beyondidentity.android.sdk:embedded:[version]'
}

Swift

Swift Package Manager

From Xcode

1. From the Xcode File menu, select Add Packages and add the following url:

https://github.com/gobeyondidentity/bi-sdk-swift

2. Select a version and hit Next.
3. Select a target matching the SDK you wish to use.

From Package.swift

1. With Swift Package Manager, add the following dependency to your Package.swift:

dependencies: [
    .package(url: "https://github.com/gobeyondidentity/bi-sdk-swift.git", from: [version])
]

2. Run swift build

Cocoapods

Add the pod to your Podfile:

pod 'BeyondIdentityEmbedded'

And then run:

pod install

After installing import with

import BeyondIdentityEmbedded

React Native

Using react-native init or an expo app.

react-native init

Install the SDK with yarn or npm:

yarn add @beyondidentity/bi-sdk-react-native

npm install @beyondidentity/bi-sdk-react-native

Update native requirements in your ios and android folders:

iOS

Make sure your ios/Podfile supports "minimum deployment target" 13.0 or later

ios/Podfile

platform :ios, '13.0'

Navigate to your ios folder and run:

cd ios && pod install

Android

Make sure your android/build.gradle supports minSdkVersion 26 or later

android/build.gradle

buildscript {
  ext {
    minSdkVersion = 26
  }
}

Add the following maven url to your repositories in your android/build.gradle

allprojects {
  repositories {
    maven {
      url "https://packages.beyondidentity.com/public/bi-sdk-android/maven/"
    }
  }
}

expo

info

This package requires custom native code and can be used with Development builds or prebuild and cannot be used with Expo Go.

npx expo install @beyondidentity/bi-sdk-react-native

Add the SDK config plugin to the plugins array of your app.{json,config.js,config.ts}:

{
  "expo": {
    "plugins": [["@beyondidentity/bi-sdk-react-native"]]
  }
}

The SDK requires certain minimum native versions. Set these requirments with expo-build-properties.

npx expo install expo-build-properties

{
  "expo": {
    "plugins": [
      ["@beyondidentity/bi-sdk-react-native"],
      [
        "expo-build-properties",
        {
          "android": {
            "minSdkVersion": 26
          },
          "ios": {
            "deploymentTarget": "13.0"
          }
        }
      ]
    ]
  }
}

Finally, rebuild your app as described in Expo's Adding custom native code guide.

Flutter

Pub.Dev

Add the Beyond Identity Embedded SDK to your dependencies

dependencies:
  bi_sdk_flutter: x.y.z

and run an implicit flutter pub get.

Update Android

Please make sure your android/build.gradle supports minSdkVersion 26 or later.

buildscript {
  ext {
    minSdkVersion = 26
  }
}

Update iOS

Please make sure your project supports "minimum deployment target" 13.0 or later. In your ios/Podfile set:

platform :ios, '13.0'

Prerequisites

Before making a call to initialize, you must import the Embedded namespace from the SDK.

JavaScript

import { Embedded } from '@beyondidentity/bi-sdk-js';

Kotlin

import com.beyondidentity.embedded.sdk.EmbeddedSdk

Swift

import BeyondIdentityEmbedded

React Native

import { Embedded } from '@beyondidentity/bi-sdk-react-native';

Flutter

import 'package:bi_sdk_flutter/embeddedsdk.dart';

Parameters

JavaScript

Parameter	Type	Description
config	Config	An optional configuration object.
↳ allowedDomains string[] An optional list of allowed domains. ↳ logger Log An optional interface for logging with method write(...data: any[]): void;.

Kotlin

Parameter	Type	Description
allowedDomains	List<String>?	Optional array of domains that we whitelist against for network operations. This will default to Beyond Identity's allowed domains.
app	Application	Required. The application context.
biometricAskPrompt	String	A prompt the user will see when asked for biometrics while extending a passkey to another device. Defaults to app.getString(R.string.embedded_export_biometric_prompt_title).
keyguardPrompt	((allow: Boolean, Exception?) -> Unit) -> Unit?	Required. If no biometrics is set, this callback should launch the keyguard service and return the answer.
logger	(String) -> Unit	Required. Custom logger to get logs from the SDK.

Swift

Parameter	Type	Description
allowedDomains	[String]?	An optional array of whitelisted domains for network operations. This will default to Beyond Identity's allowed domains when not provided or is empty.
biometricAskPrompt	String	Required. A prompt the user will see when asked for biometrics.
logger	((OSLogType, String) -> Void)?	Optional function to log output.
callback	@escaping (Result<Void, BISDKError>) -> Void	Required. A callback function that returns the result of the initialization operation.

React Native

Parameter	Type	Description
biometricAskPrompt	string	Required. A prompt the user will see when asked for biometrics.
allowedDomains	string[]?	An optional array of whitelisted domains for network operations. This will default to Beyond Identity's allowed domains when not provided or is empty.

Flutter

Parameter	Type	Description
biometricAskPrompt	String	Required. A prompt the user will see when asked for biometrics while extending a passkey to another device.
allowedDomains	List<String>?	Optional array of domains that we whitelist against for network operations. This will default to Beyond Identity's allowed domains.
logger	Future<Function>?	Custom logger to get logs from the SDK. To enable logging, pass EmbeddedSdk.enableLogger, otherwise, pass null.

Returns

On success, returns an instance of the Embedded class.

Examples

Example: create an instance of the Embedded namespace prior to calling its functions

JavaScript

// --- Initialize with required arguments
try {
  const embedded = await Embedded.initialize();
  console.log("Initialization successful", embedded);
} catch (error) {
  console.error("Initialization failed:", error);
}

// --- Initialize with required and optional arguments
const config = {
  allowedDomains: ["example.com", "another-example.com"],
  logger: function (logType, message) {
    console.log(`[${logType}] ${message}`);
  },
};

try {
  const embedded = await Embedded.initialize(config);
  console.log("Initialization successful", embedded);
} catch (error) {
  console.error("Initialization failed:", error);
}

Kotlin

// --- Initialize with required arguments
EmbeddedSdk.init(
  app = this,
  keyguardPrompt = { allowCallback ->
    // launch the keyguard service and then
    // call allowCallback with the result
  },
  logger = { logMessage ->
    Log.d("BeyondIdentityLog", logMessage)
  }
)

// --- Initialize with required and optional arguments
EmbeddedSdk.init(
  app = this,
  keyguardPrompt = { allowCallback ->
    // launch the keyguard service and then
    // call allowCallback with the result
  },
  logger = { logMessage ->
    Log.d("BeyondIdentityLog", logMessage)
  },
  biometricAskPrompt = getString(R.string.embedded_export_biometric_prompt_title),
  allowedDomains = listOf("example.com", "another-example.com")
)

Swift

// --- Initialize with required arguments
Embedded.shared.initialize(
  biometricAskPrompt: "Please provide your biometric"
) { result in
  switch result {
  case .success():
    print("Initialization successful")
  case .failure(let error):
    print("Initialization failed: \(error)")
  }
}

// --- Initialize with required and optional arguments
Embedded.shared.initialize(
  allowedDomains: ["example.com", "another-example.com"],
  biometricAskPrompt: "Please provide your biometric",
  logger: { (logType, message) in
    print("\(logType): \(message)")
  }
) { result in
  switch result {
  case .success():
    print("Initialization successful")
  case .failure(let error):
    print("Initialization failed: \(error)")
  }
}

React Native

// --- Initialize with required arguments
try {
  const response = await Embedded.initialize("Please provide your biometric");
  console.log(response);
} catch (error) {
  console.error("Initialization failed:", error);
}

// --- Initialize with required and optional arguments
try {
  const response = await Embedded.initialize(
    "Please provide your biometric", [
    ("example.com", "another-example.com"),
  ]);
  console.log(response);

  Embedded.logEventEmitter.addListener(
    "BeyondIdentityLogger",
    (message: string) => {
      console.log(message);
    }
  );
} catch (error) {
  console.error("Initialization failed:", error);
}

Flutter

// --- Initialize with required arguments
EmbeddedSdk.initialize('Please provide your biometric');

// --- Initialize with required and optional arguments
EmbeddedSdk.initialize(
  'Please provide your biometric',
  allowedDomains: ["example.com", "another-example.com"],
  logger: EmbeddedSdk.enableLogger
).then(() {
  print('Initialization successful');
}).catchError((error) {
  print('Initialization failed: $error');
});