NAV

Introduction

Hello, and welcome to the Ada documentation hub! This is our place to store documentation on our publicly accessible APIs, libraries, and utilities.

Audience

This document is primarily intended for developers and individuals with some practical programming experience.

Embed2

Embed2 is a small JavaScript script that embeds your Ada Chat bot into your web page. It comes equipped with various settings and actions to tailor the end-user experience.

Quick Start

1. Turn on your bot

The first step towards adding your Ada Chat Bot to your web page is to turn on the Web Chat integration in your Settings > Platforms page.

2. Embed script

<head>
  ...
  <script
    id="__ada"
    data-handle="<YOUR-BOT-HANDLE>"
    src="https://static.ada.support/embed2.js"
  ></script>
</head>

Be sure to replace <YOUR-BOT-HANDLE> with your own bot handle. It's usually the name of your company.

Once you have your website all ready-to-go, find the page where you'd like to embed the Ada Chat bot. In most cases this will be an HTML file. Here you will need to paste the following into the <head> tag.

3. That's it! 🎉

You should now see a small question mark button on the bottom right corner of your page. Clicking the button will toggle the Web Chat in and out of view.

You can see see a working example here.

Advanced Setup

In some situations, the quick setup above may be too simplistic. You may want to delay instantiation of Embed2 until a certain event, your application might be a Single-Page App and you need more control, or perhaps you want to set the bot language. Whatever the reason, Embed2 ships with additional features to help you get setup.

If you still require recommendations on how best to implement the Embed2 script, please reach out to an Ada team member. However, please note that all implementations are ultimately the responsiblity of your development team.

Ada Settings

<script>
  window.adaSettings = {
    ...
  }
</script>
...
<!-- Define the Embed script afterwards -->

Embed2 supports a number of configurable options which can be set through an adaSettings object you define on your window scope. Alternatively, settings can also be passed to the adaEmbed.start method (see Lazy Mode below).

A full list of adaSettings options can be found in API Reference.

Lazy Mode

<script
  id="__ada"
  data-lazy
  data-handle="<YOUR-BOT-HANDLE>"
  src="https://static.ada.support/embed2.js"
></script>

Start Embed2 in your JS when you are ready to.

window.adaEmbed.start({
  handle: "my-bot",
  metaFields: {
    username: "Ada Lovelace",
    phone_number: "123-456-7890"
  },
  chatterTokenCallback: (chatter) => console.log(chatter)
});

Lazy mode can be configured to delay Embed2 instantiation. To put Embed2 in lazy mode, add the attribute data-lazy to the Embed2 script.

When you are ready to instantiate Embed2, call the start action. You can pass any settings you would normally set in window.adaSettings here.

Async

<script
  async
  id="__ada"
  data-handle="<YOUR-BOT-HANDLE>"
  src="https://static.ada.support/embed2.js"
></script>

Approach 1: Use the native script onload handler

<script
  async
  id="__ada"
  onload="window.adaEmbed.toggle()"
  data-handle="<YOUR-BOT-HANDLE>"
  src="https://static.ada.support/embed2.js"
></script>

Approach 2: Use the adaReadyCallback

window.adaSettings = {
  adaReadyCallback: () => {
    window.adaEmbed.toggle();
  }
};

Since HTML5, the async attribute has been available for HTML script elements. From MDN, it "allows the elimination of parser-blocking JavaScript where the browser would have to load and evaluate scripts before continuing to parse". It may be applied to the Embed2 script in order to improve load times of your page, however it does come with certain caveats.

If your bot implementation makes use of any actions from the global adaEmbed object, you must wait for the object to be added to your document. There are two common approaches for handling this situation.

Approach 1 involves using the native script onload handler. When the script has loaded, the load event will be triggered. It is safe to call adaEmbed actions from here.

Approach 2 involves using the adaReadyCallback, which you can set in window.adaSettings. Note that while in the examples provided toggle will work effectively the same way, adaReadyCallback is triggered after adaEmbed.start(...) has executed. Meanwhile, onload is simply triggered when the Embed2 script has been loaded.

RequireJS

<script>
  window.adaSettings = {
    handle: "<YOUR-BOT-HANDLE>"
  };
</script>

<script
  src="https://static.ada.support/embed2.js"
></script>

If you are using RequireJS as your module loader, you may encounter issues with the standard Embed2 setup. This is because RequireJS does not know how to interpret the id and data-handle attributes Ada uses. Instead of setting this attributes, you can just set handle in your window.adaSettings object.

If you experience additional errors be sure to check out the RequireJS Common Errors documentation.

Upgrading From Embed1

If you are coming to Embed2 from Embed1, great! Upgrading couldn't be simpler. For basic setups, you most likely just need to upgrade you Embed script src from "https://static.ada.support/embed.js" to "https://static.ada.support/embed2.js".

Although the Embed2 API is almost identical to Embed1, in some cases features have been removed or modified. You can find a comprehensive list of changes below.

Embed1 Feature Status Comments
authCallback Modified Renamed to zdChatterAuthCallback.
crossWindowPersistence Modified Simplified to accept a boolean instead of an object.
dragAndDrop Deprecated
mobileOverlay Deprecated
private Modified Renamed to privateMode.
styles Deprecated

Additionally, all actions have been modified to return Promises.

API Reference

Embed2 supports numerous settings and actions to help you customize the look and behaviour of your bot. Settings are set in the adaSettings object when you embed your script. They determine intrinsic properties like bot style and behaviour. Conversely, actions can be called at any point in time to toggle Chat, update user meta data, and more.

Settings

Settings are set on the window object as window.adaSettings = { ... }. Alternatively, they can be passed directly do adaEmbed.start({ ... }) for advanced configurations. A full list of available settings is provided below:

adaReadyCallback

<script type="text/javascript">
  window.adaSettings = {
    adaReadyCallback: ({ isRolledOut }) => {
      console.log("Ada Embed is done setting up. Chat support is now available.");
    }
  }
</script>

adaReadyCallback?(params: { isRolledOut: boolean }): void;

Specifies a callback function to be called when Embed2 has finished setting up. This is especially useful when Embed2 is loaded asynchronously.

chatterTokenCallback

chatterTokenCallback?(chatter: string): void;

Specifies a callback for when the chatter token has been set in Chat. This is called when chat is first opened by a chatter.

cluster

cluster?: string;

Specifies the Kubernetes cluster to be used. Unless directed by an Ada team member, you will not need to change this value.

crossWindowPersistence

crossWindowPersistence?: boolean;

When set enables the Chat drawer open / close state to persist across windows and page refreshes using the Window.sessionStorage API. When the browser is closed the state is forgotten.

customDomains

<script type="text/javascript">
  window.adaSettings = {
    customDomains: {
      embedModern: "https://my-cdn.com/embed2/<hash>/client-modern.js",
      embedLegacy: "https://my-cdn.com/embed2/<hash>/client-legacy.js"
    }
  }
</script>

customDomains?: { embedLegacy: string; embedModern: string; };

To reduce bundle size for users on modern browsers, Embed2 dynamically loads either a modern or legacy client script. However, this also means that serving Embed2 from your own domain is not as easy as hosting the entry script.

To get around this issue, the customDomains option can be used to specify the dynamic client scripts (which you have self-hosted).

domain

domain?: string;

Can be used to change the subdomain. Unless directed by an Ada team member, you will not need to change this value.

greeting

greeting?: string;

This can be used to customize the greeting messages that new users see. This is useful for setting page-specific greetings across your app. The greeting should correspond to the ID of the Answer you would like to use. The ID can be found in the URL of the corresponding Answer in the dashboard.

handle

handle:? string;

Can be used to specify the bot handle if one is not specified in the script data-handle attribute.

hideMask

hideMask?: boolean;

When set to true, this will prevent the default mask from appearing over top of your site's content when opened on desktop.

language

language?: string;

Takes in a language code to programatically set the bot language. Languages must first be turned on in the Settings > Multilingual page of your Ada dashboard. Language codes follow the ISO 639-1 language format.

metaFields

<script type="text/javascript">
  window.adaSettings = {
    metaFields: {
      phone_number: "(123) 456-7890",
      name: "Ada Lovelace"
    }
  }
</script>

metaFields?: object;

Used to pass meta information about a chatter. This can be useful for tracking information about your end users, as well as for personalizing their experience. For example, you may wish to track the phone_number and name for conversation attribution. Once set, this information can be accessed in the email attachment from Handoff Form submissions, or via the Chatter Info modal in the Conversations page of your Ada dashboard. Should you need to programatically change these values after bot setup, you can make use of the setMetaFields action below.

lazy

lazy?: boolean;

When true, this will prevent the bot from loading until the adaEmbed.start(...) method is called.

onAdaEmbedLoad

window.adaSettings = {
  onAdaEmbedLoad: () => {
    window.adaEmbed.subscribeEvent("ada:campaigns:shown", (data) => {
      console.log("Message received from campaign with key:", data.campaignKey);
    });
  }
};

Called when the embed script has been loaded, and before it is initialized. This is useful for subscribing to events (see subscribeEvent) - subscribing here ensures subscriptions are in place before events are triggered.

parentElement

<head>
  <!-- ... -->
  <script type="text/javascript">
    window.adaSettings = {
      parentElement: document.getElementById("custom-iframe")
    }
  </script>
</head>
<body>
  <!-- ... -->
  <div id="custom-iframe"></div>
</body>

parentElement?: string | HTMLElement;

Specifies where to mount the <iframe> if the default side drawer is not desired. Accepts the HTMLElement or element id of the desired parent element.

privateMode

privateMode?: boolean;

If set to true, this will put Web Chat into "Private" mode. This will cause Web Chat to forget conversation history on refresh. This is effectively the same as setting your Web Chat platform persistence to "Forget After Reload" in the Settings > Platforms page of your Ada dashboard. More information on persistence can be found here.

rolloutOverride

rolloutOverride?: number;

Can be used to override the rollout value set in the dashboard. This can be useful if you need page-specific rollout values. Accepts any number between 0 and 1.

testMode

testMode?: boolean;

Marks the chatter as a test user.

toggleCallback

toggleCallback?(isDrawerOpen: boolean): void;

Can be used to trigger side-effects when the Web Chat drawer is opened or closed.

zdChatterAuthCallback

zdChatterAuthCallback?(callback: (token: string) => void): void;

window.adaSettings = {
  zdChatterAuthCallback: (callback) => {
    // Here you should make a request to get the fresh JWT token
    const token = "token goes here";
    callback(token)
  }
};

When called, the zdChatterAuthCallback can be used to request a JWT token from your API, and then have it passed to Ada. This allows for a shared trust between Ada and Zendesk, and in turn for verifiable chatter identity.

Actions

Actions can be called from the global adaEmbed object. A list of the available actions is available below.

createProactive [deprecated]

Note: although it is currently still supported, createProactive will be deprecated in the future. triggerCampaign should be favored.

window.adaEmbed.createProactive("Hi there! Is there something I can help you with?", 10, "5e9481e296ac6c4467092be5");

createProactive(body: string, duration?: number, responseId?: string): Promise<void>;

Can be used to programatically create a proactive intro message. If an Answer ID is provided, that answer will be triggered when Chat is opened. createProactive returns a Promise, which can be used to wait for one proactive intro before displaying the next.

This action requires the developer_proactive feature flag to be turned on.

deleteHistory

deleteHistory(): Promise<void>;

Deletes the chatter used to fetch conversation logs for an end-user from storage. When a user opens a new Chat window a new chatter will be generated.

evaluateCampaignConditions

window.adaEmbed.evaluateCampaignConditions({
  ignoreStatus: false,
  ignoreFrequency: false
});

evaluateCampaignConditions(options: object): Promise<void>;

This is similar to triggerCampaign - however, instead of triggering a specific Campaign, evaluateCampaignConditions evaluates the trigger conditions of the Campaigns in priority order and triggers the first Campaign (if any) whose conditions are matched. This can be useful, for example, if Embed2 cannot determine that the route has changed and the campaign trigger rules need to be evaluated again.

An optional argument options can be passed. These options may be helpful when testing your Campaign. The options are: - ignoreStatus?: boolean: if ignoreStatus is true, inactive and draft Campaigns will also have their trigger conditions evaluated and may be triggered. - ignoreFrequency?: boolean: if ignoreFrequency is true, Campaigns that have already been triggered within the frequency configured on the Campaign will also have their trigger conditions evaluated and may be triggered.

This action requires the Ada Engage Campaigns feature.

getInfo

getInfo(): Promise<WindowInfo>;

Returns an object containing information about the bot, including hasActiveChatter, hasClosedChat, and isChatOpen.

reset

window.adaEmbed.reset({
  greeting: "5e9481e296ac6c4467092be5"
});

reset(resetParams?: ResetParams): Promise<void>;

Creates a new chatter and refreshes the Chat window. reset can take an optional object allowing language, metaFields, and greeting to be changed for the new chatter.

To prevent creating a new chatter (and maintain conversation history), resetChatHistory can be passed to the object with a value of false.

setMetaFields

window.adaEmbed.setMetaFields({
  phone_number: "(123) 456-7890",
  name: "Ada Lovelace"
});

setMetaFields(options: object): Promise<void>;

Used to update metaFields after Chat has been opened. In most situations, the metaFields settings object should be enough for user attribution. However, in cases where Ada Chat remains open while page changes occur (like in Single Page Applications), this methods may be useful.

start

window.adaEmbed.start({
  handle: "my-bot",
  language: "fr",
  mobileOverlay: true
});

start(adaSettings: StartOptions): Promise<void>;

Used to initialize Embed2 on your page. This action is triggered by default internally, so you will likely not need to call it directly unless you are using Embed2 is lazy mode, or have called stop and want to re-start Embed2.

stop

stop(): Promise<void>;

Removes Embed2 from your page.

subscribeEvent

subscribeEvent(eventKey: string, callback: (data: object, context: object) => void): Promise<number>

window.adaEmbed.subscribeEvent("ada:campaigns:shown", (data) => {
  console.log("Message received from campaign with key:", data.campaignKey);
});
window.adaEmbed.subscribeEvent("ada:campaigns", (data, context) => {
  const { eventKey } = context;

  if (eventKey === "ada:campaigns:shown") {
    console.log("Message received from campaign with key:" data.campaignKey);
  }

  if (eventKey === "ada:campaigns:opened") {
    console.log("Chat opened after being shown campaign with key:" data.campaignKey);
  }

  if (eventKey === "ada:campaigns:engaged") {
    console.log("Chatter engaged with campaign with key:" data.campaignKey);
  }
});

When certain events happen in Ada, events will be triggered. Each event consists of an event key and a data payload. Using subscribeEvent, you can define callbacks that get called when a specific event is triggered.

Callbacks will be triggered whenever an event starts with the eventKey provided to subscribeEvent. This allows subscribing to all events of a certain category - for example, the callback in a subscription to ada:campaigns will be called on ada:campaigns:shown, ada:campaigns:opened, and any other events beginning with ada:campaigns.

Two arguments will be provided to each callback when it is called: data and context. data is specific to each event (see table below). context is an object with a single property eventKey, which is the event key of the event that triggered the callback to be called.

subscribeEvent returns a number subscriptionId which can be used to unsubscribe later (see unsubscribeEvent below).

It is strongly recommended that initial subscriptions to events be placed in the onAdaEmbedLoad function. This ensures that the embed script has been loaded (so it is available to accept subscriptions), and that subscriptions happen before any events are triggered so that no events are missed.

The following is a list of the currently available events that can be subscribed to. More events may be added in the future.

Event key Data Description
ada:campaigns:shown campaignKey - the key of the campaign which triggered the received message Triggered when the chat application receives a message that originates from a campaign.
ada:campaigns:opened campaignKey - the key of the last campaign shown before chat was opened Triggered when chat is opened after a proactive campaign has been shown.
ada:campaigns:engaged campaignKey - the key of the last campaign shown before the conversation was engaged Triggered when the chatter engages a conversation (sends a message) after being shown a campaign in the same session.

unsubscribeEvent

unsubscribeEvent(subscriptionId: number): void;

const subscriptionId = await window.adaEmbed.subscribeEvent("ada:campaigns:shown", (data) => {
  console.log("Message received from campaign with key:", data.campaignKey);
});

window.adaEmbed.unsubscribeEvent(subscriptionId);

This function can be used to remove subscriptions created with the subscribeEvent function above. It takes a single parameter subscriptionId, which is the id of the subscription to be removed.

toggle

toggle(): Promise<void>;

Can be used to programatically open / close the Chat window. This method cannot be used with the parentElement option.

triggerCampaign

window.adaEmbed.triggerCampaign("Example_Campaign", {
  ignoreStatus: false,
  ignoreFrequency: false
});

triggerCampaign(campaignKey: string, options: object): Promise<void>;

Used to trigger the proactive Campaign with key campaignKey.

An optional second argument options can be passed. These options may be helpful when testing your Campaign. The options are: - ignoreStatus?: boolean: if ignoreStatus is true, the Campaign will be triggered even if it is inactive or in a draft state. - ignoreFrequency?: boolean: if ignoreFrequency is true, the Campaign will be triggered even if it has already been triggered within the frequency configured on the Campaign.

This action requires the Ada Engage Campaigns feature.

trackEvent

window.adaEmbed.trackEvent("Example_Event", 2, {
  productId: "a1b2c3",
  customerSegment: "premium"
});

trackEvent(eventKey: string, value?: number, meta?: object)

Used to track an Event. The arguments to this function are: - eventKey: string: (required) the key of the Event to track. - value?: number: an optional value to assign to the Event. - meta?: object: an option object containing metadata corresponding to the Event. For example, it may be useful to track information such as currency, product group, customer segment, etc.

This action requires the Ada Engage Events feature.

FAQ

How do I setup Ada Chat for my mobile app?

Ada now has native support for both iOS and Android apps! Find out more about iOS here, and Android here.

How do I customize the look and feel of the Ada Chat button?

Ada supports multiple options for button configuration through the dashboard. Without any code, you can customize attributes such as the button colour, size, and icon.

How do I customize the look and feel of the Chat window?

Basic branding, including colours and icons, can be configured through the Ada dashboard.

Ada Embed is rendered as soon as the page loads. How can I delay rendering?

Embed2 features a useful data attribute called data-lazy. When defined on your script, Embed2 will not be triggered until you manually call adaEmbed.start(...). Alternatively, the lazy property can be passed to the window.adaSettings. See Advanced Setup for more information.

Versioning

The Embed script found above is versionless. This means that the latest stable features will be made available to you without any changes to your code.

Browser Support

Embed supports all major browsers, including Chrome, FireFox, Safari, Edge, IE11+, and mobile browsers.

iOS SDK

The Ada iOS SDK is a small framework that is used to embed your Ada Chat bot into your native iOS application.

iOS Installation

The Ada iOS SDK can be installed manually or using CocoaPods. The SDK supports iOS 10.x and up.

Option 1: Manual Integration

  1. Download the AdaEmbedFramework.framework.zip file from the latest release here.
  2. Right click on the project file in XCode, then click "Add Files to MyProjectName". Ensure that the Copy groups option is selected.
  3. Ensure your Deployment Target is set to 10.0, which is the minimum iOS version that the Ada iOS SDK is compatible with.
  4. In the project settings under General, link the AdaEmbedFramework.framework under the Embedded Binaries section. You can do this by dragging the framework from the left side list in the Embedded Binaries list.

Option 2: CocoaPods

# Podfile
platform :ios, '10.0'

target 'MyApp' do
  use_frameworks!

  # Pods for MyApp
  pod "AdaEmbedFramework", "~>1.3.0"

end

Be sure to get the latest version at https://cocoapods.org/pods/AdaEmbedFramework.

The AdaEmbedFramework CocoaPod is public, however use of the Chat interface is gated. To gain access please reach out to an Ada Account Manager.

  1. Add the AdaEmbedFramework to your Podfile.

  2. Install the pod using:

pod install

Quick Start

import AdaEmbedFramework

# ...

lazy var adaFramework = AdaWebHost(handle: "ada-example")

Once you have installed the Ada iOS SDK, you are ready to use it in your app! To start, import AdaEmbedFramework into your controller. Then, create an instance of the AdaWebHost.

The lazy property prevents AdaWebHost from initializing until the property is used. Use of this property may help to prevent unwanted chatters from being created in the background.

Please note "ada-example" is being used for demonstration purposes. Be sure to sure modify "handle", as well as any other values as needed for your bot.

Finally, launch Ada using any of the 3 opening methods: launchModalWebSupport, launchNavWebSupport, or launchInjectingWebSupport.

API

Settings

AdaWebHost can take various input parameters to customize the behaviour of your Chat bot.

appScheme

appScheme: String = ""

Can be used to pass the scheme name of the host app. This allows for more robust handling of universal links.

cluster

cluster: String = ""

Specifies the Kubernetes cluster to be used. Unless directed by an Ada team member, you will not need to change this value.

greeting

greeting: String = ""

This can be used to customize the greeting messages that new users see. This is useful for setting view-specific greetings across your app. The greeting should correspond to the ID of the Answer you would like to use. The ID can be found in the URL of the corresponding Answer in the dashboard.

handle

handle: String

The handle for your bot. This is a required field.

language

language: String = ""

Takes in a language code to programatically set the bot language. Languages must first be turned on in the Settings > Multilingual page of your Ada dashboard. Language codes follow the ISO 639-1 language format.

metaFields

lazy var adaFramework = AdaWebHost(handle: "ada-example", metafields: ["tier": "pro"])

metafields: [String: String]? = [:]

Used to pass meta information about a Chatter. This can be useful for tracking information about your end users, as well as for personalizing their experience. For example, you may wish to track the phone_number and name for conversation attribution. Once set, this information can be accessed in the email attachment from Handoff Form submissions, or via the Chatter modal in the Conversations page of your Ada dashboard. Should you need to programatically change these values after bot setup, you can make use of the setMetaFields method below.

openWebLinksInSafari

openWebLinksInSafari: Bool = false

External web links now open by default in-app via the SFSafariViewController. To open external links in the Safari browser, pass openWebLinksInSafari: true to AdaWebHost.

zdChatterAuthCallback

zdChatterAuthCallback: ((((_ token: String) -> Void)) -> Void)? = nil

lazy var adaFramework = AdaWebHost(handle: "nic", zendeskAuthCallback: { callback in
    // Request JWT from your API
    // Then...
    callback("your.JWT")
})

When called, the zdChatterAuthCallback can be used to request a JWT token from your API, and then have it passed to Ada. This allows for a shared trust between Ada and Zendesk, and in turn for verifiable chatter identity.

Actions

deleteHistory

deleteHistory()

Deletes the chatter used to fetch conversation logs for an end-user from storage. When a user opens a new Chat window a new chatter will be generated.

launchInjectingWebSupport

adaFramework.launchInjectingWebSupport(into: injectingView)

launchInjectingWebSupport(into view: UIView)

Launches Ada Chat into a specified subview.

launchModalWebSupport

adaFramework.launchModalWebSupport(from: self)

launchModalWebSupport(from viewController: UIViewController)

Launches Ada Chat in a modal view overtop your current view.

launchNavWebSupport

adaFramework.launchNavWebSupport(from: navigationController)

launchNavWebSupport(from navController: UINavigationController)

Pushes a view containing Ada Chat to the top of your navigational stack.

reset

reset()

Can be used to create a new chatter and refresh the Chat window.

setMetaFields

adaFramework.setMetaFields([
    "firstName": "Jane",
    "lastName": "Doe",
    "tier": "pro"
])

setMetaFields(_ fields: [String: Any])

Used to set meta data for a chatter after instantiation. This is useful if you need to update user data after Ada Chat has already launched.

Android SDK

The Ada Android SDK is a small framework that is used to embed your Ada Chat bot into your native Android application.

Android Installation

The Ada Android SDK can be installed manually or using Gradle.

Manual

The Ada Android SDK can be installed manually from the .aar file. Files can be found here.

// build.gradle
dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar', '*.aar'])
}

To install the library you need to save the .aar file under your app module libs folder, for example MyAwesomeProject/app/libs, and include *.aar in application level build.gradle file.

After that, synchronize the project.

You can also import a file using Android Studio. To do this, go to File -> New -> New Module. In the window select Import .JAR/.AAR Package and click Next. After that, specify the path to the .aar file and the module name, and click Finish.

// build.gradle
implementation project(':new_module_name')

Finally, define the implementation for the new local library module.

Gradle

// build.gradle
allprojects {
    repositories {
        maven {
            url "https://gitlab.com/api/v4/projects/25892134/packages/maven"
        }
    }
}

The Ada Android SDK can be installed using Gradle from the Ada Support Gitlab repository.

To integrate the SDK, first add the following code to the project level build.gradle file.

If your project has artifacts within the AndroidX namespace, use:

implementation 'support.ada.embed:android-sdk-appcompat:1.3.8'

If your project uses Android Support Library, use:

implementation 'support.ada.embed:android-sdk-appcompat-legacy:1.3.8'

Be sure to get the latest version at https://gitlab.com/adasupport/androidsdk/-/packages.

Next, add the dependency to the application level build.gradle.

Quick Start

After installing the SDK, you can start Ada chat in several ways.

XML

<!-- XML -->
<support.ada.embed.widget.AdaEmbedView
        android:id="@+id/ada_chat_frame"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        app:ada_handle="ada-example" />

Please note "ada-example" is being used for demonstration purposes. Be sure to modify the handle, as well as any other values as needed for your bot.

The simplest way to start Ada Chat is via XML.

To display the view, the ada_handle parameter is required. If you specify it as an attribute, the chat will be displayed immediately upon attachment to the parent view. If it is not specified, then you can do it later programmatically using the method initialize(settings: AdaEmbedView.Settings).

// Delayed initialization
val adaView = findViewById(R.id.ada_chat_frame)

adaSettings = AdaEmbedView.Settings.Builder("ada-example")
    .build()
adaView.initialize(adaSettings)

Programmatically

val adaView = AdaEmbedView(getContext())

val adaSettings = AdaEmbedView.Settings.Builder("ada-example")
    .build()
adaView.initialize(adaSettings)

To programmatically create the chat frame, you need to create a view object and pass context to the constructor.

After this, the view will be created, but will not be initialized. To do this call initialize(settings: AdaEmbedView.Settings), passing the settings object as an argument.

Finally, to display the newly created chat frame on screen, simply add the view to your container.

Dialog

val dialog = AdaEmbedDialog()
 adaDialog.arguments = Bundle().apply {
    putParcelable(AdaEmbedDialog.ARGUMENT_SETTINGS, settings)
 }
dialog.show(supportFragmentManager, AdaEmbedDialog.TAG)

Note that TAG is a simple class name, you can use any value you want.

To display a separate chat window on top of the current window, you can use AdaEmbedDialog.

First, create a dialog object and pass the settings to its arguments using a constant AdaEmbedDialog.ARGUMENT_SETTINGS.

Then show it using the native Android show method.

Activity

val intent = Intent(context, AdaEmbedActivity::class.java)
intent.putExtra(AdaEmbedActivity.EXTRA_SETTINGS, settings)
context.startActivity(intent)

Note that you can use "AdaEmbedActivity" as a regular Android activity. For example, flags and actions can be added.

The SDK allows you to open the chat window in a separate window attached to the app navigation. For this you need to use AdaEmbedActivity.

Create an Intent and put the settings in it with the key AdaEmbedActiviti.EXTRA_SETTINGS and run the activity.

Send Files

adaView.filePickerCallback = { filePickerCallback ->
    filePickerCallback.onFileTaken(someUri)
    true
}

When using Ada Glass (for Zendesk live agent support), end users sometimes need to upload files. AdaEmbedActivity and AdaEmbedDialog already have this functionality, but if you work directly with AdaEmbedView you have to handle it yourself.

To do this, you need to setup a callback to AdaEmbedView. This callback will be fired when a user requests to attach a file. When you get the URI you can invoke filePickerCallback.onFileTaken(someUri); it will signal to AdaEmbedView that the file is ready to attach. It's also possible to pass null, which will cancel the request.

This operation doesn't require you to pass the file URI to callback immediately. You can save filePickerCallback and invoke the callback later (eg. take URI via file picker).

To notify AdaEmbedView that you are going to handle file attach you should return true.

Third-Party Cookies

app:ada_accept_third_party_cookies = "true"

The SDK has support for third-party cookies. Note that apps targeting Build.VERSION_CODES.KITKAT and lower already allow third-party cookies by default.

API

Settings

<!-- Example 1: XML -->
<support.ada.embed.widget.AdaEmbedView
        android:id="@+id/ada_chat_frame"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        app:ada_handle="ada-example"
        app:ada_cluster="ca"
        app:ada_language="en"
        app:ada_handle="ada-example"
        app:ada_greetings="5c59aaabd8269e0339979014"/>
// Example 2: Kotlin
val adaSettings = AdaEmbedView.Settings.Builder("ada-example")
    .cluster("ca")
    .greetings("5c59aaabd8269e0339979014")
    .language("en")
    .metaFields(metaFieldsMap)
    .build()

Using the SDK, you can configure the initial chat settings for greater customization. Settings can be configured for XML, or programmatically using theAdaEmbedView.Settings class.

cluster

Specifies the Kubernetes cluster to be used. Unless directed by an Ada team member, you will not need to change this value.

greeting

This can be used to customize the greeting messages that new users see. This is useful for setting view-specific greetings across your app. The greeting should correspond to the ID of the Answer you would like to use. The ID can be found in the URL of the corresponding Answer in the dashboard.

handle

The handle for your bot. This is a required field.

language

Takes in a language code to programmatically set the bot language. Languages must first be turned on in the Settings > Multilingual page of your Ada dashboard. Language codes follow the ISO 639-1 language format.

metaFields

Used to pass meta information about a Chatter. This can be useful for tracking information about your end users, as well as for personalizing their experience. For example, you may wish to track the phone_number and name for conversation attribution. Once set, this information can be accessed in the email attachment from Handoff Form submissions, or via the Chatter modal in the Conversations page of your Ada dashboard.

You can also set "meta fields" using XML. For this, you need to create a JSON file in the res/raw directory, and set the reference to the view declaration:

zdChatterAuthCallback

When using AdaEmbedView

adaView.zdChatterAuthCallback = {
    getToken() // this functions returns String
}

When using AdaEmbedDialog

val adaDialog = AdaEmbedDialog()
adaDialog.zdChatterAuthCallback = {
    getToken() // this functions returns String
}

When called, the zdChatterAuthCallback will request a JWT token (probably generated by your API), and then have it passed to Ada. This allows for validation between your App and Ada that the user is authenticated, and in turn between Ada and Zendesk for verifiable chatter identity.

To implement, zdChatterAuthCallback must be defined on adaView, or adaDialog. If the SDK requests a JWT token, this callback will be fired.

Actions

deleteHistory

adaView.deleteHistory()

Deletes the chatter used to fetch conversation logs for an end-user from storage. When a user opens a new Chat window, a new chatter will be generated.

To do this you need to call deleteHistory() in your AdaEmbedView instance.

reset

Creates a new chatter and refreshes the Chat window. Reset can take an optional params: language, metaFields, and greeting to be changed for the new chatter.

To prevent creating a new chatter (and maintain conversation history), param resetChatHistory can be passed with a value of false.

To do this you need to call reset() in your AdaEmbedView instance: kotlin adaView.reset() Or with optional params:

val metaFields = hashMapOf("name" to "John", "age" to "20")
adaView.reset(language = "fr", metaFields = metaFields)

setMetaFields

val metaFields = hashMapOf("name" to "John", "age" to "20")
adaView.setMetaFields(metaFields)

The SDK allows you to change your meta fields while the chat frame is displayed.

To do this you need to call setMetaFields() in your AdaEmbedView instance and pass your new meta fields as an argument:

AdaEmbedActivity & AdaEmbedDialog

// AdaEmbedActivity
class MyCustomActivity : AdaEmbedActivity(){
    override fun onResume() {
        super.onResume()
        val adaView = getAdaView()
        adaView.setMetaFields(metaFields)
        adaView.deleteHistory()
        adaView.reset()
    }
}

To call actions in the AdaEmbedActivity, you first need to create your own activity that inherits AdaEmbedActivity. Then using the getAdaView() you can obtain the AdaEmbedView instance:

// AdaEmbedDialog
val adaDialog = supportFragmentManager.findFragmentByTag(AdaEmbedDialog.TAG) as AdaEmbedDialog
adaDialog.setMetaFields(metaFields)
adaDialog.deleteHistory()
adaDialog.reset()

To call actions in the AdaEmbedDialog, you can obtain AdaEmbedDialog instance from FragmentManager:

React Native SDK

The Ada React Native SDK is a small framework that is used to embed your Ada Chat bot into your React Native application.

Installation

# With npm
npm install --save @ada-support/react-native-sdk

# With yarn
yarn add @ada-support/react-native-sdk

The Ada React Native SDK is based on react-native-webview. Before you can use the SDK, you will need to follow the react-native-webview "Getting Started Guide".

When you've configured react-native-webview, simply install the Ada React Native SDK via NPM.

Quick Start

import AdaEmbedView from '@ada-support/react-native-sdk';
// ...

class MyComponent extends React.Component {
  render() {
    return <AdaEmbedView handle="ada-example"/>;
  }
}

Once you have installed the Ada React Native SDK, you are ready to use it in your app! Simply import the AdaEmbedView component, then render it. Note that you must pass a valid handle for the Chat window to work.

File Permissions

Some functionality in the Ada Chat bot will not work unless permissions are explicitly given.

iOS

<!-- Photo capture -->
<key>NSCameraUsageDescription</key>
<string>Take pictures for certain activities</string>

<!-- Gallery selection -->
<key>NSPhotoLibraryUsageDescription</key>
<string>Select pictures for certain activities</string>

<!-- Video recording -->
<key>NSMicrophoneUsageDescription</key>
<string>Need microphone access for recording videos</string>

For iOS, all you need to do is specify the permissions in your ios/[project]/Info.plist file.

Android

<manifest ...>
  ...
  <!-- this is required only for Android 4.1-5.1 (api 16-22)  -->
  <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
  ...
</manifest>

For Android, add permissions in AndroidManifest.xml.

API

Props

AdaEmbedView can take various props to customize the behaviour of your Chat bot.

cluster

cluster?: string;

Specifies the Kubernetes cluster to be used. Unless directed by an Ada team member, you will not need to change this value.

greeting

greeting?: string;

This can be used to customize the greeting messages that new users see. This is useful for setting view-specific greetings across your app. The greeting should correspond to the ID of the Answer you would like to use. The ID can be found in the URL of the corresponding Answer in the dashboard.

handle

handle: string;

The handle for your bot. This is a required field.

language

language?: string;

Takes in a language code to programatically set the bot language. Languages must first be turned on in the Settings > Multilingual page of your Ada dashboard. Language codes follow the ISO 639-1 language format.

metaFields

metaFields={{
  name: "Some name",
  age: 30
}}

metaFields?: object;

Used to pass meta information about a chatter. This can be useful for tracking information about your end users, as well as for personalizing their experience. For example, you may wish to track the phone_number and name for conversation attribution. Once set, this information can be accessed in the email attachment from Handoff Form submissions, or via the Chatter modal in the Conversations page of your Ada dashboard. Should you need to programatically change these values after bot setup, you can make use of the setMetaFields method below.

thirdPartyCookiesEnabled (Android)

thirdPartyCookiesEnabled?: boolean;

The thirdPartyCookies prop can be set to enable third-party cookies in the AdaEmbedView. This feature is only available in Android. The default value is false.

zdChatterAuthCallback

zdChatterAuthCallback?(callback: (token: string) => void): void;

zdChatterAuthCallback={callback => {
  const token = getTokenFromAPI(); // Get a fresh JWT token from your API
  callback(token);
}}

The zdChatterAuthCallback can be used to request a JWT token from your API, and then have it passed to Ada. This allows for a shared trust between Ada and Zendesk, and in turn for verifiable chatter identity.

Actions

import AdaEmbedView from '@ada-support/react-native-sdk';
// ...

class MyComponent extends React.Component {
  render() {
    return <AdaEmbedView
            handle="ada-example"
            ref={ref => (this.adaEmbedView = ref)}/>;
  }
}

Actions can be called directly from the AdaEmbedView ref. This allows you to modify Ada Chat without using state/props to trigger a re-render of the entire subtree.

deleteHistory

this.adaEmbedView.deleteHistory();

Deletes the chatter used to fetch conversation logs for an end-user from storage. When a user opens a new Chat window, a new chatter will be generated.

reset

this.adaEmbedView.reset();

// With options
this.adaEmbedView.reset({
  metaFields: {
    name: "Some name",
    age: 30
  },
  resetChatHistory: false
});

Creates a new chatter and refreshes the Chat window. reset can take an optional object allowing language, metaFields, and greeting to be changed for the new chatter.

To prevent creating a new chatter (and maintain conversation history), resetChatHistory can be passed to the object with a value of false.

setMetaFields

this.adaEmbedView.setMetaFields({
  name: "Some name",
  age: 30
});

Used to set meta data for a chatter after instantiation. This is useful if you need to update user data after Ada Chat has already launched.

Questions

Need some help? Get in touch with us at help@ada.support.