Xamarin Android SDK Overview

To set up the Xamarin Android SDK, follow the steps below:

1. Gather Required information
2. Add the NuGet Package to your Project
3. Create a Config
4. Launch Chat
5. Authenticate the Chat User
6. Implement the ASAPP Callback Handlers
7. Customize the UI

1. Gather Required Information

To successfully integrate and test the ASAPP SDK, you will need the following information:

ASAPP repository username & token	Allows you access to download the ASAPP Chat SDK NuGet package. Provided by ASAPP.
App ID	Also known as the “company marker”, assigned by ASAPP.
API Hostname	The fully-qualified domain name used by the SDK to communicate with ASAPP’s API. Provided by ASAPP and subject to change based on the stage of implementation.
Region Code	The ISO 3166-1 alpha-2 code for the region of the implementation. Provided by ASAPP. Default is “US”.
Client Secret	This can be an empty or random string until otherwise notified by ASAPP. See note below.
Customer Identifier	A username or similar value used to identify and authenticate the customer. Depending on the stage of implementation, customer identifiers for testing purposes may or may not be provided by ASAPP.
Authentication Token	A password-equivalent value, which may or may not expire, used to authenticate the customer.

In the future, the client secret will be a string, provided by ASAPP, that authorizes the integrated SDK to call the ASAPP API in production. ASAPP recommends that you fetch this string from a server and store it securely using Android KeyStore or iOS Keychain; however, as it is one of many layers of security, you can hard-code the client secret.

2. Add the NuGet Package to your Project

Before you start, make sure you have a username and token that allow you access to the Xamarin Chat SDK distribution repository - please contact your ASAPP Implementation Manager if you don’t have access yet.

After you have a username and token, select one of the following integration options depending on your needs.

When you add the NuGet package, make sure that you compile your project.

Option 1: Visual Studio

Windows: reference

• In the Solutions Explorer, select Tools > Options. The Options window opens.
• In left side menu, expand NuGet Package Manager and select Package Sources.
• In upper right corner, press add + button. It adds a new source in the list set:
  • Name: ASAPP ChatSDK
  • Source: https://packages.asapp.com/chat/sdk/xamarin/index.json.
• Press the Update button to set the actual name and source to the list item.
• Press OK to close the Options window.
• Right-click on Solution and select Manage NuGet Packages for Solution. The NuGet Package Manager in the VS tab opens.
• Change the source to ASAPP ChatSDK. The Credentials window opens.
• Enter your username and token and press Login. After you login, you will see the ASAPP.SDK NuGet package when you browse the ASAPP NuGet feed.
• Install the NuGet package to your Android and/or iOS projects.

Mac: Reference

• In Visual Studio, select Preferences > NuGet > Sources. A list of all NuGet sources opens.
• Click the Add button (bottom right). A window for adding the package source opens.
• Enter the following information:
  • Name: ASAPP ChatSDK
  • Location: https://packages.asapp.com/chat/sdk/xamarin/index.json
  • Username: <username>
  • Password: <token>
• Select Add Source to add the ASAPP ChatSDK source to Visual Studio NuGet Sources.
• In the main menu, select Project > Manage NuGet Packages. The Manage NuGet Packages window opens.
• In the dropdown menu, select ASAPP ChatSDK and ASAPP.SDK NuGet package and add them to your Android/iOS projects.

Option 2: NuGet.Config file

In the Solution folder, create a new NuGet.Config file, open in a text editor and add:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <packageSources>
        <add key="ASAPP ChatSDK" value="https://packages.asapp.com/chat/sdk/xamarin/index.json" />
    </packageSources>
    <packageSourceCredentials>
        <ASAPP ChatSDK>
            <add key="Username" value="[Add HERE your ASAPP username]" />
            <add key="ClearTextPassword" value="[Add HERE your ASAPP token]" />
        </ASAPP ChatSDK>
    </packageSourceCredentials>
</configuration>

Save your NuGet.Config and add it to your source control. Then all users will have the ASAPP Xamarin SDK source feed added automatically.

Option 3: Manually download the NuGet package and add it to your project

In your shell, navigate to the Solution folder and add the NuGet source feed with the command:

nuget sources Add -Name "ASAPP ChatSDK" -Source https://packages.asapp.com/chat/sdk/xamarin/index.json -UserName [Your ASAPP username] -Password [Your ASAPP token] --store-password-in-clear-text

To download the ASAPP NuGet package to the current folder, run command (The install command does not modify a project file or packages.config).

nuget install ASAPP.SDK

To install the ASAPP.SDK package to your project in Visual Studio, add it as a source under Project→Add NuGet Packages.

3. Create a Config

The ASAPP class needs to be initialized once with an ASAPPConfig that defines how the SDK communicates with ASAPP’s API. The client secret can be an empty string for testing purposes; the final value will be provided by ASAPP.

using Com.Asapp.Chatsdk;

ASAPPConfig config = new ASAPPConfig(appId, apiHostName, clientSecret);
ASAPP.Init(application, config);

4. Launch Chat

At this point, chat is ready to be launched. Do so by calling openChat in the ASAPP instance. This call is usually done from a button click, and we recommend using a Floating Action Button for easy chat access.

ASAPP.Instance.OpenChat(this);

If the ASAPPUser has not been configured yet, the call above will open chat as an anonymous user. Follow the next section to setup chat authentication.

5. Authenticate the Chat User

ASAPP.User

Identify the current user who will be chatting. You may use null as the userIdentifier to begin an anonymous chat. The requestContextProvider is required.

ASAPP.Instance.User = new ASAPPUser(customerIdentifier, new ASAPPRequestContextProvider());

Request Context Provider

The ASAPPRequestContextProvider provides the SDK with the user authentication token and other data as agreed upon with ASAPP (such as analytics). The SDK calls GetASAPPRequestContext on a background thread when making network requests that require user credentials.

The refreshContext flag will be true if the previously cached context is stale and may have expired. If true, be sure to return a fresh authentication token. This operation must be done synchronously.

public class ASAPPRequestContextProvider : Object, IASAPPRequestContextProvider
{
    public IDictionary<string, Object> GetASAPPRequestContext(ASAPPUser user, bool refreshContext)
    {
        var authMap = new HashMap();
        authMap.Put("Token",  myUser.token);
        return new Dictionary<string, Object>()
        {
            { "Auth", authMap }
        };
    }
}

6. Implement the ASAPP Callback Handlers

To fully integrate ASAPP Chat, you must you must implement each callback handler with your ASAPP instance.

DeepLinkHandler

During a chat, the user may encounter and tap on a button that will redirect the user back to the host application. When such a button is tapped, the ASAPP SDK will call this method if it is implemented.

Implement IASAPPDeepLinkHandler interface.

public class ASAPPDeepLinkHandler : Java.Lang.Object, IASAPPDeepLinkHandler
{
    public void HandleASAPPDeepLink(string deepLink, JSONObject data, Activity activity)
    {
        // Handle the deepLink here.
    }
}

Set the DeepLinkHandler.

ASAPP.Instance.DeepLinkHandler = new ASAPPDeepLinkHandler();

WebLinkHandler

You can override any web link handling. By default (in case no handler is set), the SDK will open the default web browser.

Implement IASAPPWebLinkHandler interface.

public class ASAPPWebLinkHandler : Java.Lang.Object, IASAPPWebLinkHandler
{
        public void HandleASAPPWebLink(string webLink, Activity activity)
        {
                Toast.MakeText(p1, $"webLink: {p0}", ToastLength.Long).Show();
        }
}

Set WebLinkHandler.

ASAPP.Instance.WebLinkHandler = new ASAPPWebLinkHandler();

UserLoginHandler

When an anonymous chat user reaches a point where authentication is required, the ASAPP SDK will make a call to the ASAPPUserLoginHandler.

Note: if your app does not allow users to access ASAPP chat anonymously, you can skip this.

Implement the IASAPPUserLoginHandler interface.

public class ASAPPUserLoginHandler : Java.Lang.Object, IASAPPUserLoginHandler
{
    public void LoginASAPPUser(int requestCode, Activity activity)
    {
        Intent loginIntent = new Intent(activity, typeof(MyLoginActivity));
        activity.StartActivityForResult(loginIntent, requestCode);
    }
}

Set UserLoginHandler.

ASAPP.Instance.UserLoginHandler = new ASAPPUserLoginHandler();

The Chat Login Process is as follows:

1. Your app will starts its own LoginActivity, using activity.StartActivityForResult with the provided activity and request code.
2. If user successfully logs in: a. Set the new ASAPP user, see User Authentication. b. Set an OK activity result, like SetResult(Result.Ok). c. Finish the activity.

   ASAPP.Instance.SetUser(newAsappUser, context);
   SetResult(Result.Ok);
   Finish();
   

3. And if the user cancels the login: a. Set a cancelled activity result, like SetResult(Result.Canceled). b. Finish the activity.

   SetResult(Result.Canceled);
   Finish();
   

7. Customize the UI

Please see ASAPP Android SDK API documentation.

Customization is done via the ASAPPStyleConfig class.Android SDK Reference

ASAPP will provide a code snippet to customize the SDK according to a design that has been agreed upon.