Overview

This guide walks you through the steps to install and initialize any of Nextiva’s SDKs: React, React Native, or Web. All SDKs follow a similar installation process with slight variations depending on your frontend framework.

Prerequisites

Install any modern package manager (npm, yarn, bun, pnpm).

npm and node.js installation instructions

Install the SDK

Install the appropriate SDK based on your platform. You can use any modern package manager (npm, yarn, bun, pnpm).

npm install @nextiva/ncx-react-sdk @twilio/voice-sdk axios libphonenumber-js rxjs zustand

yarn add @nextiva/ncx-react-sdk @twilio/voice-sdk axios libphonenumber-js rxjs zustand

pnpm add @nextiva/ncx-react-sdk @twilio/voice-sdk axios libphonenumber-js rxjs zustand

bun add @nextiva/ncx-react-sdk @twilio/voice-sdk axios libphonenumber-js rxjs zustand

Initialize the SDK

To get started, initialize the SDK in your application's entry point (e.g., App.tsx, index.ts, or similar).

Web

import i18n, { type TOptions } from 'i18next';
import { Nextiva, type Translations, type ITranslator } from '@nextiva/ncx-web-sdk';

class Translator implements ITranslator {
  load(language: string, translations: Translations): void {
    i18n.addResourceBundle(language, 'translation', translations);
  }

  translate(key: string, options: TOptions): string {
    return i18n.t(key, options);
  }
}

const sdk = new Nextiva({
  baseURL: 'YOUR_API_BASE_URL',
  debug: true,
  language: 'en',
  translator: new Translator(),
});

React

import i18n, { type TOptions } from 'i18next';
import { Nextiva, type Translations, type ITranslator } from '@nextiva/ncx-react-sdk';

class Translator implements ITranslator {
  load(language: string, translations: Translations): void {
    i18n.addResourceBundle(language, 'translation', translations);
  }

  translate(key: string, options: TOptions): string {
    return i18n.t(key, options);
  }
}

const sdk = new Nextiva({
  baseURL: 'YOUR_API_BASE_URL',
  debug: true,
  language: 'en',
  translator: new Translator(),
});

React Native

import i18n, { type TOptions } from 'i18next';
import { Nextiva, type Translations, type ITranslator } from '@nextiva/ncx-react-native-sdk';

class Translator implements ITranslator {
  load(language: string, translations: Translations): void {
    i18n.addResourceBundle(language, 'translation', translations);
  }

  translate(key: string, options: TOptions): string {
    return i18n.t(key, options);
  }
}

const sdk = new Nextiva({
  baseURL: 'YOUR_API_BASE_URL',
  debug: true,
  language: 'en',
  translator: new Translator(),
});

Wrap in provider

This step only applies to the React and React Native SDKs. Wrap your app in the NcxSdkProvider so the SDK instance is accessible across your component tree:

// This sdk is the one created in the initialization step.
<NcxSdkProvider ncxSdk={sdk}> 
{/* Your app components */}
</NcxSdkProvider>

Authenticate users

After installing and initializing the SDK, authenticate users by calling the login() method and initialize the session with init().

Example: React SDK

import { useNcxSdk } from '@nextiva/ncx-react-sdk';

function YourLoginComponent() {
  const ncxSDK = useNcxSdk();

  const handleLogin = async (username, password) => {
    try {
      const response = await ncxSDK.login(username, password);
      
      if (response.token) {
        await ncxSDK.init();
        navigate(paths.home());
      }
    } catch (error) {
      alert('Invalid credentials');
    }
  };
}

Example: Web SDK

  try {
      const response = await ncxSDK.login(username, password);
      
      if (response.token) {
        await ncxSDK.init();
        navigate(paths.home());
      }
    } catch (error) {
      alert('Invalid credentials');
    }

Language support

Language parameter

The language option passed during SDK initialization sets the localization context. It ensures all SDK-generated messages (e.g. errors, statuses) are returned in the correct language. English is default.

Translator setup (optional)

To enable dynamic translation, implement a custom Translator class using a library like i18next.

import i18n, { type TOptions } from 'i18next';
import { type Translations, type ITranslator, Logger } from '@nextiva/ncx-react-sdk';
 
export class Translator implements ITranslator {
  load(language: string, translations: Translations): void {
	i18n
  	.changeLanguage(language)
  	.then(() => {
    	i18n.addResourceBundle(language, 'translation', translations);
  	})
  	.catch((error: unknown) => {
    	Logger.error(error);
  	});
  }
 
  translate(key: string, options: TOptions): string {
	return i18n.t(key, options);
  }

Debug mode

Enable SDK debug logs by setting the debug flag to true during initialization. This will surface helpful logs in your browser or terminal console.

Base URL/tenant

The baseURL defines which tenant the SDK will connect to (e.g. companyname.nextiva.com)
Make sure this URL matches your assigned Nextiva tenant domain.

Example VUE integration

While this guide covers React and Web primarily, the SDK can also be initialized in a Vue environment using the same pattern for initialization and login. A provider component is not required in Vue.