Guides
  1. SDK
  2. Web SDK

Web SDK Functions

Initialize

The init function initializes the Alloy SDK by setting up the essential resources and configurations needed for the SDK to operate correctly.

Parameters

OptionTypeDetails
keystringClient-specific public SDK key that is tied to your Alloy Journey. Required
journeyApplicationTokenstringToken of an application. Required if using Step Up, not required if using device or behavioral plugin.
productionbooleanSetting this to true will make the SDK use the Alloy production endpoints. Required
appUrlstringRequired for non-US regions and specific Alloy tenants. Reach out to your Alloy rep for the correct value
apiUrlstringRequired for non-US regions and specific Alloy tenants. Reach out to your Alloy rep for the correct value
journeyTokenstringToken that refers to that particular journey, Required
entityTokenstringPass entity token into init params for multi-entity applications to send each applicant only their portion of the doc verification process. Optional
isSingleEntitybooleanSend each applicant in a joint application only their portion of document process. Optional
showHeaderbooleanShow the header at the top of the SDK with the exit button and entity name. Default is true. Optional
isReactNativebooleanIndicate that it's a react native application. Default is false. Optional
  • Prevents script calls to the window object, which is unavailable in the React Native environment.
  • Ensures proper communication between the React application and the React Native WebView by handling callbacks for the onComplete event effectively.
colorobjectSpecify different values for the main colors of the SDK. Optional
color.primarystringSpecify hex color for primary color of SDK
color.secondarystringSpecify hex color for secondary color of SDK
runtimePlatformstringIndicates that the SDK should start in "web" or "hybrid" mode. Optional by default "web" is used.
removeClosingDelaybooleanRemoves the closing fade-out animation after the SDK flow completes successfully. Optional
skipBehavioralPluginsFetchbooleanSkips the API call to set up behavioral plugins. Intended for use only when no behavioral plugins are configured. Reduces latency. Optional
languagestringSets the language for supported plugins. Accepts ISO 639-1 language codes (e.g., 'fr', 'de', 'es'). Currently supported by SumSub. Optional

Usage

Device and behavioral profiling

Use this initialization when you only need to profile the end user's device or collect behavioral signals.

  • No journeyApplicationToken is required because no document collection step is involved.
  • alloy.init() returns an object that includes alloyRequestFields — a flat map of session tokens collected from active behavioral and fraud detection plugins (e.g., socure_session_id, neuro_user_id, threatmetrix_session_id). 
alloy.init({
  key: "ecfb58b7-a611-4fbd-b727-1b1d2113411a",
  journeyToken:"J-YCMHdHquF111111eM9"
});
📘

Tip

For the most accurate results, initialize profiling as early as practical in the user journey. However, avoid profiling too far in advance of when the profiled session will be sent through Alloy to the third-party data provider for evaluation, as long delays may reduce the effectiveness of the collected signals.


Document collection

Use this initialization when the Journey includes document verification.

  • journeyApplicationToken is required to associate the SDK session with a specific application.
  • Set skipBehavioralPluginsFetch: true if no behavioral plugins are configured — this skips an unnecessary API call and reduces latency.
alloy.init({
  key: "ecfb58b7-a611-4fbd-b727-1b1d2113411a",
  production: true,
  skipBehavioralPluginsFetch: true,
  journeyApplicationToken: "JA-hlZa11yUJYkTNzUTl116",
  journeyToken:"J-YCMHdHquF111111eM9"
});

Returns

The following values are sample values, and will be specific to your account/application.

{
  key : "ecfb58b7-a611-4fbd-b727-1b1d2113411a",
  journeyApplicationToken : "JA-hlZa11yUJYkTNzUTl116",
  journeyToken : "J-YCMHdHquF111111eM9",
  iovationBlackbox : "113asd1312-asdlkjl-11mmdgfg" // Only applicable if using Iovation
  neuroIdSiteId : "site-123", // Only applicable if using Neuro-ID
  neuroUserId : "8222528f-8657-4bdf-90a3-46779966cd11", // Only applicable if using Neuro-ID
  socureDeviceId : "device-123", // Only applicable if using Socure Device Risk
  socurePublicToken : "e11e126f80-ba23-4113-96aa-3a63d511f311", // Only applicable if using Socure Device Risk
  alloyRequestFields: {
    socure_session_id: "abc123",
    neuro_user_id: "8222528f-8657-4bdf-90a3-46779966cd11",
    site_id: "site-123",
    threatmetrix_session_id: "tmx-session-456",
    org_id: "org-789"
  }
}

alloyRequestFields

📘

Note

Only available in SDK v2.7.0 and later

The alloyRequestFields object is returned by the init function and contains a flat map of session tokens and identifiers collected from active behavioral and fraud detection plugins. The keys in this object reflect the field names expected by the Alloy backend API, and can be merged into the payload when creating a Journey Application or Evaluation without any additional field mapping.

Preload Modal

Available in SDK v2.6.0 and later. Optional — the SDK works without calling preload; use it only when you want to minimize the time between a user action and the modal appearing.

The preload function warms up the SDK in the background by injecting a hidden iframe that downloads the Alloy frontend assets and initializes its runtime ahead of time. When open is later called, the existing iframe is revealed instead of being created from scratch, making the modal appear instantly.

Preload can be called before or after init. If called before init, the iframe boots in a lightweight warm-up mode and receives its configuration via postMessage once open runs — no reload is required.

Parameters

OptionTypeDetails
parent componentstringThe HTML ID of the HTML element the hidden SDK container should mount inside of.

Usage

// Call as early as possible (e.g. on page load) to warm up the SDK.
alloy.preload("renderComponent");

// Later, when the user is ready to verify:
alloy.init({
	key: "ecfb58b7-a611-4fbd-b727-1b1d2113411a",
	production: false,
	journeyApplicationToken: "JA-hlZa11yUJYkTNzUTl116",
	journeyToken: "J-YCMHdHquF111111eM9"
});

alloy.open(callback);

Returns

This SDK function does not return any object.

📘

Notes

Calling preload is entirely optional — it is a performance optimization, not a prerequisite for init or open. For best results, call preload as early in the page lifecycle as possible so the bundle is fully loaded before the user triggers open.

Open Modal

The open function displays the SDK modal, allowing users to interact with the SDK's interface.

Parameters

OptionTypeDetails
callbackfunctionFunction to be executed when the SDK is closed via the Exit button.
parent componentstringThe HTML ID of the HTML element the SDK should mount inside of.

Usage

alloy.open(callback, "renderComponent");

This is a sample callback function. It is recommended to parse the application status from the returned object to handle different outcomes appropriately. The callback function will be executed when the Exit button is clicked by the user. For more details on the structure of the returned data object, refer to the following sectioRead more about the data object structure returned here

function callback(data) {  
   console.log(data.journey_application_status)
}

Returns

None

📘

Note

Ensure alloy.init() has been called before using open.

Close Modal

The close function will close the Alloy SDK interface, terminating any active processes and returning control to the calling application.

Parameters

None

Usage

alloy.close();

Returns

None

Data Structure Returned in Callback

The following data structure is returned as a parameter in your callback function. Below are the attributes included in this data object.

{
  journey_application_token: string;
  external_partner_id: string | null;
  external_group_id: string | null;
  external_application_id: string | null;
  status: string;
  sandbox: boolean;
  created_at: number;
  updated_at: number;
  closed_at: number | null;
  recent_outcome: string | null;
  complete_outcome: string | null;
  journey_application_status: string;
  is_archived: boolean;
  is_escalated: boolean;
  is_shadow_application: boolean;
  is_part_of_shadow_test: boolean;
  is_rerun: boolean;
  archived_at: number | null;
  terminal_reconciliation_output: Record<string, unknown>;
  _embedded: {
    rerun: Record<string, unknown>;
    child_entities: Array<{
      external_entity_identifier: string;
      name: string;
      token: string;
      type: string;
      entity_application_token: string;
      entity_application_status: string;
      entity_application_outcome: string | null;
      entity_application_branch_name: string;
      created: string;
      sandbox_persona_name: string | null;
    }>;
    entity_applications: Array<{
      entity_token: string;
      entity_application_token: string;
      entity_application_outcome: string | null;
      entity_application_status: string;
      sdk_link: string | null;
      entity_application_status_details: string | null;
      external_entity_identifier: string;
      output: {
        outcome_reasons: Array<{
          name: string;
          type: string | null;
        }>;
        tags: string[];
        output_attributes: Record<string, unknown>;
        matrix_models: Record<string, unknown>;
      };
    }>;
    entity: {
      external_entity_identifier: string | null;
      name: string | null;
      token: string;
      type: string;
    };
    events: Array<{
      journey_application_event_token: string;
      journey_application_token: string;
      type: string;
      journey_type: string;
      timestamp: number;
      entity_token: string;
      entity_application_token: string | null;
      _embedded: {
        node: {
          id: string | null;
          name: string | null;
          type: string | null;
          config?: Record<string, unknown>;
          workflow_name?: string;
        };
      };
      _links: Record<string, unknown>;
      evaluation_token?: string;
      outcome?: string;
      case_token?: string;
      evaluation_tokens_sorted_by_created_dec?: string[];
    }>;
    journey: {
      journey_name: string;
      journey_type: string;
      journey_token: string;
      journey_version_num: string;
      _links: {
        self: {
          href: string;
        };
        callback_by_entity_application_token?: Record<string, unknown>;
      };
    };
  };
  _links: {
    self: {
      href: string;
    };
  };
  sdk: {
    sdkEvent: string;
  };
}

Get Public URL

The getPublicUrl function will return the public-facing URL that displays the SDK. This function is ideal for react-native applications.

Parameters

None

Usage

alloy.getPublicUrl()

Returns

A string containing the public URL is returned. This URL includes the parameters that were configured in the init function.

'https://alloysdk.alloy.co/?journeyApplicationToken=JA-hlZa4Ty110YkTNzUTlX26&journeyToken=J-YCMHdH22FYld4x5adeM9&key=ecfb3337-a6eb-4fbd-b727-1b3d2863409a'

Updated 14 days ago

Did this page help you?