Xamarin iOS SDK Overview

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

1. Gather Required Information
2. Add the NuGet Package to your Project
3. Create a Config
4. Set the User and Add Other Required Code
5. Launch Chat
6. Customize the UI

​

1. Gather Required Information

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

​

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;

var config = new ASAPPConfig(appId, apiHostname, "", regionCode);
ASAPP.InitializeWith(config);

Make sure that your project compiles at this point.

​

4. Set the User and Add Other Required Code

​

ASAPP.user

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

ASAPP.User = new ASAPPUser(customerIdentifier, requestContextProvider);

​

Request Context Provider

The requestContextProvider provides the user’s authentication token (with key ASAPP.AuthTokenKey, required) and optionally analytics (with key ASAPP.AnalyticsKey) and other data as agreed upon with ASAPP. The SDK calls the requestContextProvider on a background thread when making a request that relies on user information.

The needsRefresh 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 can be done asynchronously since the function is called on a background thread.

private NSDictionary requestContextProvider(bool needsRefresh)
{
    var contextProvider = new Dictionary<string, object>
    {
        { ASAPP.AuthTokenKey, shared.authToken }
    };
    var result = NSDictionary.FromObjectsAndKeys(
        contextProvider.Values.ToArray(), contextProvider.Keys.ToArray());
    return result;
}

​

IASAPPDelegate

You must implement the IASAPPDelegate interface’s methods.

public class HomeViewController : BaseViewController, IASAPPDelegate
{
    #region IASAPPDelegate
    [Export("chatViewControllerDidTapUserLoginButton")]
    public void ChatViewControllerDidTapUserLoginButton()
    {
        // Called when user taps on a login button.
        // You should present UI that lets the user log in.
        // Once the user has logged in, you must set ASAPP.user
    }
    [Export("chatViewControllerDidDisappear")]
    public void ChatViewControllerDidDisappear()
    {
        // Called after the ASAPP view controller has disappeared.
    }
    [Export("chatViewControlledDidTapDeepLinkWithName:data:")]
    public void ChatViewControlledDidTapDeepLinkWithName(string name, NSDictionary data)
    {
        // Called when a user taps on a deep link to another part of the app.
    }
    [Export("chatViewControllerShouldHandleWebLinkWithUrl:")]
    public bool ChatViewControllerShouldHandleWebLinkWithUrl(NSUrl url)
    {
        // Called when a user taps on a web link.
        // Return false if the ASAPP view controller should not handle the web link and your app will handle it instead.
        return true;
    }
    [Export("chatViewControllerDidReceiveChatEventWithName:data:")]
    public override void ChatViewControllerDidReceiveChatEventWithName(string name, NSDictionary data)
    {
        // Called when certain agreed-upon events occur during a chat.
    }
    #endregion

Make sure that your project compiles at this point.

​

5. Launch Chat

There are four methods for creating a chat view controller. Which method you should call is determined by how you want to display the view controller.

If the chat is being displayed because the user tapped a push notification, the notification’s userInfo dictionary should be passed in when creating the chat view controller. When a push notification is received, please call ASAPP.CanHandleNotificationWith to check that the ASAPP SDK can handle the notification’s payload before displaying chat. To create a chat view controller outside the context of a push notification, pass in null.

Push (Navigation Controller)

var controller = ASAPP.CreateChatViewControllerForPushingFromNotificationWith(userInfo);

Presentation (Modal)

var controller = ASAPP.CreateChatViewControllerForPresentingFromNotificationWith(userInfo);

​

Launch Chat with an Intent

To create a chat view controller that will start a user in a specific state, pass a dictionary describing an initial intent. If there is a business need, ASAPP’s Implementation Manager will provide details.

var dictionary = new Dictionary<string, object> {{ "Code", "EXAMPLE_INTENT" }};
var intent = NSDictionary.FromObjectsAndKeys(dictionary.Values.ToArray(), dictionary.Keys.ToArray());

Push (Navigation Controller)

var controller = ASAPP.CreateChatViewControllerForPushingWithIntent(intent);

Presentation (Modal)

var controller = ASAPP.CreateChatViewControllerForPresentingWithIntent(intent);

​

Set an Intent with Chat Already Launched

If an ASAPP chat view controller has already been created and displayed, use SetIntent(NSDictionary data).

ASAPP.SetIntent(intent)

​

Launch Chat on Simulator

When you develop on the iOS simulator, enable the Keychain entitlement and add a keychain access group for the application’s bundle identifier.

Open the Entitlements.plist in the iOS project and find the Keychain entitlement and enable it. This automatically adds the application’s identifier as a group. In the project properties under iOS Bundle Signing, set the Custom Entitlements to Entitlements.plist.

​

6. Customize the UI

Please see the ASAPP iOS SDK documentation for full details about all customizable styles, such as text or background colors and font sizes.

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