Latest 1.3.2
Homepage https://github.com/iadvize/iadvize-ios-sdk
License Proprietary
Platforms ios 9.3
Dependencies MessageKit, Apollo, JWT, SwiftGraylog
Authors

iAdvize – iOS Conversation SDK

Take your app to the next step and provide a unique conversational experience to your users!

Embed the iAdvize Conversation SDK in your app and connect your visitors with your professional agents or ibbü experts through a fully customised chat experience. Visitors can ask a question and will receive answers directly on their devices with push notifications, in or outside your app.

You will find an example of integration in the Example/IAdvizeSwiftExample folder of this repository.

Just run pod install, open the IAdvizeSwiftExample.xcworkspace and run the project. You can copy and paste the Podfile into your project to easily test it into your app.

Compatibility

Version Minimum iOS Version Swift Version
1.3.2 iOS 9.3 Swift 4.2
1.3.1 iOS 9.3 Swift 4.2
1.3.0 iOS 9.3 Swift 4.2
1.2.2 iOS 9.3 Swift 4.2
1.2.1 iOS 9.3 Swift 4.2
1.2.0 iOS 9.3 Swift 4.2
1.1.0 iOS 9.3 Swift 4.2
1.0.2 iOS 9.3 Swift 4
1.0.1 iOS 9.3 Swift 4
1.0.0 iOS 9.3 Swift 4

Integration

Customisation

Integration

App creation

Ask your iAdvize Admin to create a “Mobile App” on the administration website and to give you those two information displayed in the “Mobile App” list (application ID, JWT secret).

To create the Mobile App, you will need to provide to your Administrator some information regarding the push notifications:

Having your push certificate .p12 file (a Production one, which we can use for both Sandbox and Production environment), you have to extract the Certificate and the Private key in clear text.

To do so, simply run in your Terminal :

openssl pkcs12 -in AppProductionPushCertificate.p12 -out Cert.pem -nodes -clcerts

then cat Cert.pem and you can copy/paste the certificate and the private key and provide it as printed in the Terminal.

You can register your application to the SDKStatusDelegate in IAdvizeManager to be informed when the SDK is enabled or disabled in the iAdvize administration website.

SDK dependency

Cocoapods

Using Cocoapods, add this line to your Podfile:

pod 'iAdvize'

then run pod install to fetch the dependency.

Logging

By default, the SDK will only log Warnings and Errors in the Xcode console. You can make it more verbose and choose between multiple levels of log for a better integration experience:

IAdvizeManager.shared.logLevel = .verbose

Language

By default, the SDK will use the device language for targeting a conversation. With this variable you can specify the language you want to use for targetting:

IAdvizeManager.shared.language = SDKLanguageOption.custom(value: .fr)

Registering your application ID

Using the application ID (see App creation above), you can register your application by calling:

IAdvizeManager.shared.registerApplicationId("your-own-application-identifier-uuid")

Activating the SDK

You have two ways to activate the iAdvize Conversation SDK depending on the security model you choose.

  • For the in-app security model:
IAdvizeManager.shared.activate(jwtOption: .secret("yourjwtsecret"), externalId: "connecteduseruniqueidentifierornil")
  • For the server-side security model:
IAdvizeManager.shared.activate(jwtOption: .token("yourjwttoken"), externalId: "connecteduseruniqueidentifierornil")

The externalId is a unique identifier you can provide to identify your connected user across sessions and devices. It should not contain any private information (should not be an email, a phone number, a name…) of the user and should be opaque and unforgeable (e.g. a dynamic UUID). If your user isn’t logged-in you can pass a void value for this parameter (nil in Swift).

The ruleId allow to target visitors proactively or reactively, based on their browsing behaviour, their profile or their business criteria (e.g. basket amount, scoring, etc). Ask your iAdvize Admin to give you this identifier.

Once the iAdvize Conversation SDK is successfully activated, you should see a message like this in the IDE console:

iAdvize Conversation: ✅ iAdvize conversation activated, the version is x.x.x.

A completion handler is available in order to know if the SDK has been successfully activated (and to retry later if the activation fails):

IAdvizeManager.shared.activate(jwtOption: .token("yourjwttoken"), externalId: "connecteduseruniqueidentifierornil", ruleId: UUID(uuidString: "targetingruleid")) { success, isEnabled in
}

N.B. You have to check if the activation succeeds before you try to show a Chat Button (the default or a custom one). You also have to check the isEnabled flag which indicates you if the SDK is currently enabled or disabled by the SDK Administrator.

GDPR

By default when you activate the SDK, the GDPR will be disabled. You can activate the GDPR feature by passing a new parameter to the activate method and provide a mandatory Legal Information URL link with it:

IAdvizeManager.shared.activate(jwtOption: .token("yourjwttoken"), externalId: "connecteduseruniqueidentifierornil", gdprOption: .enabled(URL("https://www.iadvize.com/en/legal-notice/")), ruleId: UUID(uuidString: "targetingruleid")

The GDPR process is now activated for your users and a default message will be provided to collect the user consent. Please check the Customise section below if you want to customise this message.

Registering push token

In order to allow your users to receive operators or experts answers in real time, you should register the current push token of the device:

IAdvizeManager.shared.registerPushToken("pushtoken", applicationMode: .prod)

You can register it at any time after you activate the SDK (see Activating the SDK above).

N.B.: If you are in Debug mode you must pass applicationMode: .dev to the registerPushToken call (to properly receive push notifications). You could easily add some preprocessor macros to manage both cases:

e.g. with a DEBUG flag and preprocessor macro defined in your Build Settings for the Debug configuration:

        #if DEBUG
        IAdvizeManager.shared.registerPushToken(pushToken, applicationMode: .dev)
        #else
        IAdvizeManager.shared.registerPushToken(pushToken, applicationMode: .prod)
        #endif

Chat button

In order to invite your users to enter in a conversational experience, you have to display the default Chat button (see the Customise section below if you want to display your own). You can also, at any time, hide it. To do this you can simply use:

IAdvizeConversationManager.shared.showChatButton()
IAdvizeConversationManager.shared.hideChatButton()

By default, it will be displayed on the main window of your app (on top of any view). You can also show the Chat Button on your custom view:

IAdvizeConversationManager.shared.showChatButton(viewOrWindow: myCustomView)

Push notification

Once you receive a push notification, you can easily verify that this notification concerns the SDK and ask the SDK to handle this notification for you:

IAdvizeManager.shared.isIAdvizePushNotification(with: userInfo)
IAdvizeManager.shared.handlePushNotification(with: userInfo)

*where userInfo is the dictionary contained in the push notification.

You can easily modify the title of the push notification by adding this key in your Localizable.strings file:

iadvize_notification_title

We provides you translations which you can directly add to your Localizable.strings file if you don’t want to customise it: https://github.com/iadvize/iadvize-ios-sdk/tree/master/translations/

Registering a transaction

When you want to register a transaction within your application, you can call the following method by passing a Transaction object:

let transaction = Transaction(externalTransactionId: "transactionId", date: Date(), amount: 500.0, currency: .eur)

IAdvizeTransactionManager.shared.registerTransaction(transaction)

To customise the SDK, check the next section.

Customisation

Chat button

By default, the SDK provides you a Chat button which you can integrate as-is. You can easily implement your own Chat button and by just calling the two methods below, you will be able to present (or dismiss) the Conversation View:

IAdvizeConversationManager.shared.presentConversationViewModal()
IAdvizeConversationManager.shared.dismissConversationViewModal()

Conversation view

For the next steps, you will have access to a configuration “object” to customise all Conversation View attributes. You can access the default configuration and update it like this:

// Get the current configuration
var configuration = IAdvizeConversationManager.shared.configuration
// Update some configuration attributes
configuration.mainColor = UIColor.red
// Setup this new configuration
IAdvizeConversationManager.shared.setupConversationView(configuration: configuration)

For the next steps, we will only show you the different attributes that you can setup on this “configuration” object.

Main color

You can setup a main color on the SDK which will be applied to the color of:

  • the default Chat button (if you use it)
  • the send button in the Conversation View
  • the blinking text cursor in the “new message” input in the Conversation View
  • the background color of the message bubbles (only for sent messages)
// Update the main color
configuration.mainColor = UIColor.red

Navigation bar

You can configure the Navigation bar of the Conversation View and modify:

  • the background color
  • the main color
  • the title
// Update the background color of the navigation bar
configuration.navigationBarBackgroundColor = UIColor.black
// Update the main color of the navigation bar (color of buttons and labels inside it)
configuration.navigationBarMainColor = UIColor.white
// Update the title of the navigation bar
configuration.navigationBarTitle = "Conversation"

Font

You can update the font used in the UI of the IAdvize Conversation SDK. You just have to call this method to setup your own font:

// Update the font
configuration.font = UIFont(name: "AmericanTypewriter-Condensed", size: 11.0)

Automatic message

A first automatic message can be setup to be displayed as an operator message in the Conversation View. By default, no message will be displayed. This message will also be used and displayed when the user accepts the GDPR. You can set an automatic message through the Conversation configuration:

// Update the automatic message
configuration.automaticMessage = "Hi, just ask a question and we will answer you asap!"

GDPR message

If you want to activate the GDPR consent collect feature through the iAdvize Conversation SDK, please refer to the GDPR section above.

Once the GDPR is activated, you can easily customise the GDPR message you want to display to your users to collect their consent:

// Update the GDPR message
configuration.gdprMessage = "Your own GDPR message."

Brand avatar

You can update the brand avatar displayed for the incoming messages. You can specify an URL or a Drawable. Gifs are not supported. You can set an avatar through the Conversation configuration:

// Update the incoming message avatar with a UIImage
configuration.incomingMessageAvatar = IncomingMessageAvatar.image(image: UIImage(named: "BrandAvatar"))

// Update the incoming message avatar with an URL
if let avatarUrl = URL(string: "your-url") {
    configuration.incomingMessageAvatar = IncomingMessageAvatar.url(url: avatarUrl)
}

Well done! You’re now ready to take your app to the next step and provide a unique conversational experience to your users! 🚀

Latest podspec

{
    "name": "iAdvize",
    "version": "1.3.2",
    "license": {
        "type": "Proprietary",
        "file": "LICENSE.md"
    },
    "homepage": "https://github.com/iadvize/iadvize-ios-sdk",
    "authors": {
        "iAdvize": "[email protected]"
    },
    "summary": "iAdvize - iOS Conversation SDK",
    "description": "Embed the iAdvize Conversation SDK in your app and connect your visitors with your professional agents or ibbu00fc experts through a fully customised chat experience.",
    "source": {
        "http": "https://github.com/iadvize/iadvize-ios-sdk/releases/download/1.3.2/IAdvizeConversationSDK.cocoapods.zip"
    },
    "platforms": {
        "ios": "9.3"
    },
    "swift_version": "4.2",
    "ios": {
        "vendored_frameworks": "IAdvizeConversationSDK.framework"
    },
    "dependencies": {
        "MessageKit": [
            "~> 2.0.0"
        ],
        "Apollo": [
            "~> 0.9.3"
        ],
        "JWT": [
            "~> 3.0.0-beta.11"
        ],
        "SwiftGraylog": [
            "~> 1.0"
        ]
    }
}

Pin It on Pinterest

Share This