iOS

Overview

The Instaply SDK allows to open a conversation over Instaply between your customer and a customer representative from inside your iOS application.

Installation

1. Download the instaplysdk_1.25 file to your computer (see link on top of page)
2. Unzip the files and move them into your project directory. We usually put 3rd-party code into a subdirectory named Vendor, so we move the directory into it.
3. Link the following frameworks into your project if needed: MobileCoreServices, ImageIO, CoreMedia, AVFoundation, SystemConfiguration, MobileCoreServices
4. Ensure to have the following value in your XCode build settings: other-linker-flags: -ObjC
5. Open your app delegate file.
6. Add the following line at the top of the file below your own #import statements:

    #import "INSInstaplyAccountManager.h"
   

7. In the application:didFinishLaunchingWithOptions: method (or elsewhere where you have information about your user), insert the following code (while editing the needed fields).

    [[INSInstaplyAccountManager sharedManager] configureWithAPIKey:apiKey userID:userId type:INSUserIdTypeEmail randomNonce:nonce verificationToken:digest];
    [[INSInstaplyAccountManager sharedManager] setPreferredInstaplyStoreId:businessId];
    [[INSInstaplyAccountManager sharedManager] setFirstName:@"Herve"];
    [[INSInstaplyAccountManager sharedManager] setLastName:@"Dupont"];
    [[INSInstaplyAccountManager sharedManager] setAdditionalSearchableFields:@{
                                                                           @"Town": @"Toulon",
                                                                           @"Employer": @"Agropole",
                                                                           @"ZipCode": @"75000",
                                                                           @"Title" : @"Mr",
                                                                           @"BirthDate" : @"11/07/1978"
                                                                           }];
    [[INSInstaplyAccountManager sharedManager] setAvatarImage:[UIImage imageNamed:@"herve.jpg"]];
   

   Everything is optional except for the call to configureWithAPIKey:type: and setPreferredInstaplyStoreId:businessId The userID must be something uniquer amongst all your users and the type parameters helps us categorize correctly these id. The type parameter is an enum which values can correspond to email, telephone or others. The additional searchable fields are provided to Instaply to allow full text search in the Instaply web interface to find conversations with a specific customer based on the provided fields. Technically, it is a key-value dictionary.

   You can also set a Locale if your application is not using the same language as the phone it runs on using:

   [[INSInstaplyAccountManager sharedManager] setLocale:@"fr"];
   

The supported locales are “en”, “fr”, “nl”, “pt”, “es”. If another locale is set, the messages will show in English.

1. Insert the following line in - (void)application:(UIApplication *)app didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken

    [[INSInstaplyAccountManager sharedManager] setAPNSToken:deviceToken];
   

Swift support

If your project is written in Swift you’ll need to add a bridging header in order to be able to use Instaply’s framework which is written in Objective-C. This is what you need to add to your bridging header file:

#import "instaplysdk.h"

Usage

1. To get the number of unread messages of your customers on Instaply, you can call this method:

    [[INSInstaplyAccountManager sharedManager] getUnreadCountWithSuccess:^(NSInteger unreadCount) {
        /*Here you can update your UI to display the unread message count */
    } errorCallback:^(NSError *error) {
            /*This callback is called if there was a network problem while connecting to the Instaply servers*/
    }];
   

2. To present the conversation with the customer you can instantiate a INSThreadViewController as follows (after importing "INSThreadViewController.h" ):

       INSThreadViewController * threadViewController = [[INSThreadViewController alloc] init];

and then, for example, present it modally from the current view controller:

    [viewController presentViewController:threadViewController animated:YES completion:nil];

1. If you would like to decide how to open links that are tapped by users in conversations, one of your classes can optionally implement the following protocol

    @protocol INSThreadViewControllerDelegate<NSObject>
    -(BOOL) handleURL:(NSString *) URL;
    @end
   

   and set itself as the delegate of the INSThreadViewController that you are showing. This method should return true if your code handled the URL itself, and false if the default behaviour is ok for the current URL.

2. When your users are opening your app through a push notification from Instaply, do not forget that the best behaviour is to immediately display the conversation so that the user can respond right away.
3. It is possible to prefill the input text field of the Instaply view before displaying the controller, for example to help the user by providing context information about where he launched the controller in your app. This is done using the following method

    [threadViewController prefillMessage:@"Bonjour, auriez-vous des infos sur les nouveaux forfaits?"];
   

Integration Example

You can find an example XCode project of the integration of the Instaply SDK into an iOS app here: DemoSDK.zip

Remarks

1. The SDK only exposes a minimal set of symbols and should not interfere with other SDK that you install.
2. The SDK supports iOS up from version 7.
3. The SDK only shows error messages to the user if the conversation is visible on screen.
4. Authentication and update of user information are as resilient as possible: as long as the information has not reached our servers, the SDK will retry when the app is launched again or when the network status has changed.
5. It is not necessary to call the authentication of the SDK at every app launch, but it is not a problem.
6. Instaply user info are saved in the keychain for the service your.bundle.identifier.instaplysdk and for keys prefixed by INSTAPLY_
7. If you want to download the previous version instaplysdk.1.20.zip instaplysdk_1.23.zip