@vocale/mdk

Permissions

iOS

You will need to grant permissions on iOS to allow the device to access the microphone if you are using the recording function. If you don't, your app may crash on device and/or your app might be rejected during Apple's review routine. To do this, add this key to your app/App_Resources/iOS/Info.plist file:

<key>NSMicrophoneUsageDescription</key>
<string>Recording Practice Sessions</string>

Android

If you are going to use the recorder capability for Android, you need to add the RECORD_AUDIO permission to your AndroidManifest.xml file located in App_Resources.

<uses-permission android:name="android.permission.RECORD_AUDIO"/>

MDK Config

• Update MDKProject.json as follows. We need to include @klippa/nativescript-http and nativescript-audio as these are necessary peer dependendency NS plugins.

{
  "Externals": ["@vocale/mdk", "@klippa/nativescript-http", "nativescript-audio"],
  "NSPlugins": ["@klippa/nativescript-http@^3.0.4", "@vocale/mdk@latest"],
  "NPMPlugins": ["nativescript-audio"],
}

Usage

• Update any Page's onLoaded handler as follows

import { Vocale } from '@vocale/mdk'

const vocale = new Vocale({
  // Take these values from your Site's Dashboard in vocale.ai
  siteId: "site-id",
  apiKey: "api-key",

  // Optional
  // Use this if you want Vocale to internally trigger the clientAPI.showActivityIndicator()
  // to display a loader while processing the audio
  displayActivityIndicator: true // defaults to true
});

export default async function OnLoadedHandler(clientAPI) {
  // your own code

  // Add something like this
  try {
    /**
     * Always set the client API first (page's context).
     * You should set this before executing any other action on each page that uses Vocale
     * so that it can parse the context and the form container
     */
    vocale.setClientAPI(clientAPI);

    /**
     * Use sync form once the form has been loaded on the page
     * so that Vocale can parse your form and uploaded the data to your dashboard
     */
    await vocale.syncForm({ formId: "unique-form-id-string" })
  } catch (error) {
    // Handle errors here
  }
}

• Create a Button on your page and create "OnPress" handler like this

import { Vocale } from '@vocale/mdk'

const vocale = new Vocale({
  // Take these values from your Site's Dashboard in vocale.ai
  siteId: "site-id",
  apiKey: "api-key",

  // Optional
  // Use this if you want Vocale to internally trigger the clientAPI.showActivityIndicator()
  // to display a loader while processing the audio
  displayActivityIndicator: true // defaults to true
});

export default async function ButtonOnPressHandler(clientAPI) {
  try {
    /**
     * Always set the client API first (page's context).
     * You should set this before executing any other action on each page that uses Vocale
     * so that it can parse the context and the form container
     */
    vocale.setClientAPI(clientAPI);

    if (vocale.isRecording) {
      /**
       * Stop the recording, send a payload to Vocale's AI service
       * and attempts to fill the form with the parsed data.
       */
       await vocale.stopRecording();
    } else {
      /**
       * The formId must be the same as the one used on the OnLoaded handler.
       * The user might be asked permissions to access their mic.
       */
      await vocale.startRecording({ formId: "unique-form-id-string" }, onSuccessHandler, onErrorHandler)
    }
  } catch (error) {
    // Handle errors here
  }
}