Vivocha

@interface Vivocha : NSObject

This is the main class and main entry point of the Vivocha SDK. It lives as a singleton for the entire lifetime of the application.

To start Vivocha, use the startWithAccountID:andServID: or its variant, startAutomatic:withAccountID:andServID:, with the explicit automatic parameter.

  • + (Vivocha *)manager;

    Returns the Vivocha manager that retains all the objects that Vivocha needs to work correctly.

    Return Value

    the Vivocha singleton.

  • + (BOOL)startWithAccountID:(NSString *)accountID andServID:(NSString *)servID;

    Starts Vivocha using the accountID and ServiceID.

    Parameters

    accountID

    Your Vivocha accountID (e.g. vivocha.com/a/YOUR_ACCOUNT_ID/login)
    servID

    The serviceID for this application. You will find the ID in the iOS foundry inside the Agent Desktop’s settings.

    Return Value

    YES if Vivocha started correctly, NO otherwise.

  • + (BOOL)startWithAccountID:(NSString *)accountID
                 andServID:(NSString *)servID
                    server:(NSString *)server;

    Starts Vivocha using the accountID, ServiceID and server.

    Parameters

    accountID

    Your Vivocha accountID (e.g. vivocha.com/a/YOUR_ACCOUNT_ID/login)
    servID

    The serviceID for this application. You will find the ID in the iOS foundry inside the Agent Desktop’s settings.
    server

    The Vivocha server where your account is configured.

    Return Value

    YES if Vivocha started correctly, NO otherwise.

  • + (BOOL)startWithAccountID:(NSString *)accountID
                 andServID:(NSString *)servID
                andOptions:(VivochaOptions *)options;

    Starts Vivocha using the accountID, ServiceID and server.

    Usage example:

    [Vivocha startWithAccountID:@"my_acctid"
                  andServID:@"my_serviceid"
                 andOptions:[VivochaOptions fromBuilder:^(VivochaOptionsBuilder *builder) {
    [builder setOption:WAIT_FOR_TOKEN withNumber:WAIT_UNTIL_TOKEN_IS_SET];
    [builder setOption:ENABLE_DEVELOPER_MODE withBoolean:YES];
}]];

    Parameters

    accountID

    Your Vivocha accountID (e.g. vivocha.com/a/YOUR_ACCOUNT_ID/login)
    servID

    The serviceID for this application. You will find the ID in the iOS foundry inside the Agent Desktop’s settings.
    options

    A VivochaOptions object that permits to config some SDK behaviours.

    Return Value

    YES if Vivocha started correctly, NO otherwise.

  • + (BOOL)startWithAccountID:(NSString *)accountID
                 andServID:(NSString *)servID
                    server:(NSString *)server
                andOptions:(VivochaOptions *)options;

    Starts Vivocha using the accountID, ServiceID and server.

    Usage example:

    [Vivocha startWithAccountID:@"my_acctid"
                  andServID:@"my_serviceid"
                     server:@"custom_server_url"
                 andOptions:[VivochaOptions fromBuilder:^(VivochaOptionsBuilder *builder) {
    [builder setOption:WAIT_FOR_TOKEN withNumber:WAIT_UNTIL_TOKEN_IS_SET];
    [builder setOption:ENABLE_DEVELOPER_MODE withBoolean:YES];
}]];

    Parameters

    accountID

    Your Vivocha accountID (e.g. vivocha.com/a/YOUR_ACCOUNT_ID/login)
    servID

    The serviceID for this application. You will find the ID in the iOS foundry inside the Agent Desktop’s settings.
    server

    The Vivocha server where your account is configured.
    options

    A VivochaOptions object that permits to config some SDK behaviours.

    Return Value

    YES if Vivocha started correctly, NO otherwise.

  • + (BOOL)startAutomatic:(BOOL)automatic
         withAccountID:(NSString *)accountID
             andServID:(NSString *)servID
            andOptions:(VivochaOptions *)options;

    Starts Vivocha using the accountID and ServiceID.

    Parameters

    automatic

    If set to YES, Vivocha will automatically add itself as a listener for the following methods in the AppDelegate: application:didReceiveRemoteNotification:fetchCompletionHandler: application:didRegisterForRemoteNotificationsWithDeviceToken: application:didFailToRegisterForRemoteNotificationsWithError:. If set to NO, setPushTokenWithData: must be called inside the application:didRegisterForRemoteNotificationsWithDeviceToken: method.
    accountID

    Your Vivocha accountID (as in https://www.vivocha.com/a/YOUR_ACCOUNT_ID/login)
    servID

    The serviceID for this application. You will find the ID in the iOS foundry inside the Agent Desktop’s settings.
    options

    A VivochaOptions object that permits to config some SDK behaviours.

    Return Value

    YES if Vivocha started correctly, NO otherwise.

  • + (BOOL)startAutomatic:(BOOL)automatic
         withAccountID:(NSString *)accountID
             andServID:(NSString *)servID
             andServer:(NSString *)server
            andOptions:(VivochaOptions *)options;

    Starts Vivocha using the accountID and ServiceID.

    Parameters

    automatic

    If set to YES, Vivocha will automatically add itself as a listener for the following methods in the AppDelegate: application:didReceiveRemoteNotification:fetchCompletionHandler: application:didRegisterForRemoteNotificationsWithDeviceToken: application:didFailToRegisterForRemoteNotificationsWithError:. If set to NO, setPushTokenWithData: must be called inside the application:didRegisterForRemoteNotificationsWithDeviceToken: method.
    accountID

    Your Vivocha accountID (as in https://www.vivocha.com/a/YOUR_ACCOUNT_ID/login)
    servID

    The serviceID for this application. You will find the ID in the iOS foundry inside the Agent Desktop’s settings.
    server

    The Vivocha server where your account is configured.
    options

    A VivochaOptions object that permits to config some SDK behaviours.

    Return Value

    YES if Vivocha started correctly, NO otherwise.

  • + (BOOL)stop;

    Stops Vivocha

    Return Value

    YES if Vivocha stops correctly, NO otherwise

  • + (void)setStartCallback:(void (^)(BOOL, NSInteger, VivochaStartErrorReason,
                                   NSDictionary *))startCallback;

    Sets a callback that notifies whether Vivocha successfully downloaded the campaign configuration from the server or if it failed.

    Parameters

    startCallback

    the start callback

    		 
  • + (void)setDataCollection:(VivochaDataCollection *)dataCollection;

    Set the data collection that will be sent when a new contact is requested.

    Usage example:

    VivochaDataCollectionForm *form1 = [VivochaDataCollectionForm dataCollectionFormWithName:@"Balance" andDescription:@"Mobile credit"];
[form1 addField:[VivochaDataCollectionField fieldWithName:@"Current credit"
                                                andType:VivochaDataCollectionFieldTypeNumber
                                                andValue:@"39.90"
                                                andDescription:@"Credit" andIsVisibile:YES andIsChecked:NO]];

VivochaDataCollection *dataCollection = [VivochaDataCollection dataCollectionWithForms:@[form1]];

[Vivocha setDataCollection:dataCollection];

    Parameters

    dataCollection 
  • + (VivochaDataCollection *)getDataCollection;

    Returns the data collection that was previously set.

    Return Value

    a VivochaDataCollection object.

  • + (void)setContactColor:(VivochaContactColor)color;

    Set the contact color that the agent will see when a new contact has been started from the current application.

    Parameters

    color

    A VivochaContactColor value (e.g. VivochaContactColorOrange);

    		 
  • + (void)setTheme:(VivochaTheme *)theme;

    Sets the local theme for the SDK UI.

    There are three themes that can set the SDK appearance:

    • Default (Base) Theme
    • Local Theme
    • Remote Theme

    The Default Theme is the one that ships with the Vivocha SDK, the Local Theme is the one set by the developer through the code and the Remote Theme which is is the one set from the Vivocha Foundry in the Agent Desktop and has the highest priority in order to override both Default and Local Theme without the need of a new release in the App Store.

    Parameters

    theme

    a VivochaTheme object

    		 
  • + (void)setCustomerToken:(NSString *)customerToken;

    Sets a JWT token that permits the secure verification of a customer based on information certified from an external source (e.g. your server).

  • + (void)unsetCustomerToken;

    Removes the customer verification token set with setCustomerToken:

  • + (void)setDeveloperMode:(BOOL)enable;

    Enables/Disables the developer mode. The developer mode uses the Sandbox APNS for push notifications and the “developer” theme set in the Vivocha Foundry.

    Parameters

    enable

    YES if you want to enable the dev mode, NO (default) otherwise.

    		 
  • - (BOOL)getDeveloperMode;

    Returns YES if the developer mode is enabled.

  • - (void)disableLocationFeature;

    The Vivocha SDK enables by default a Location request feature that the Agent can use from the Agent Desktop to get the Customer’s precise GPS coordinates. It can be disabled from the Vivocha Account configuration but calling this method ensures that the feature won’t be available until a new release in the App Store where it is enabled again.

  • - (void)disableScreenshotFeature;

    The Vivocha SDK enables by default a Screenshot request feature that the Agent can use from the Agent Desktop to see the Customer’s screen. It can be disabled from the Vivocha Account configuration but calling this method ensures that the feature won’t be available until a new release in the App Store where it is enabled again.

  • - (void)disableCannedQuestionFeature;

    The Vivocha SDK enables by default a Canned Question request feature that the Agent can use from the Agent Desktop to ask questions to the Customer. It can be disabled from the Vivocha Account configuration but calling this method ensures that the feature won’t be available until a new release in the App Store where it is enabled again.

  • - (void)disableAudioVideoFeature;

    The Vivocha SDK enables by default audio and video communication between Agent and Customer. It can be disabled from the Vivocha Account configuration but calling this method ensures that the feature won’t be available until a new release in the App Store where it is enabled again.

  • - (void)disableFileSharingFeature;

    The Vivocha SDK enables by default a File Transfer feature between Agent and Customer. It can be disabled from the Vivocha Account configuration but calling this method ensures that the feature won’t be available until a new release in the App Store where it is enabled again.

  • - (void)disableChatViewAutoRestoringOnAppKill;

    Disables the chat view automatic restoring when the app is killed while the chat view is visible.

  • - (void)overrideLanguage:(NSString *)lang;

    Forces Vivocha to use a different language instead of the system’s one. This is useful if the app can use a language different from the one set by the Customer.

    Parameters

    lang

    the new language (e.g. “en”)

    		 
  • + (BOOL)isShowingSideTab;

    Returns the Side Tab visibility

    Return Value

    YES if the Side Tab is being shown, NO otherwise.

  • + (VivochaTheme *)getTheme;

    Returns the Local theme that was set by the setTheme: method.

    Return Value

    The Local theme as VivochaTheme object.

  • + (void)showChatButton;

    Shows the Side Tab button.

  • + (void)hideChatButton;

    Hides the Side Tab button.

  • + (void)notifyNewPage:(VivochaPage *)page;

    When a contact is in progress, it notifies the agent that the user moved to a different view controller.

    Parameters

    page

    The current page, as VivochaPage object.

    		 
  • + (VivochaContact *)contact;

    If a contact is in progress, it returns a VivochaContact object, otherwise returns nil.

    Return Value

    the current contact.

  • + (VivochaConversation *)conversation;

    Returns the current VivochaConversation object, otherwise returns nil.

    Return Value

    the current conversation.

  • + (void)createChatWithDataCollection:(VivochaDataCollection *)dataCollection
                  andCompletionBlock:
                      (void (^)(VivochaContact *))completionBlock;

    Creates a new chat contact.

    Usage example:

    VivochaDataCollectionForm *form1 = [VivochaDataCollectionForm dataCollectionFormWithName:@"Balance" andDescription:@"Mobile credit"];
[form1 addField:[VivochaDataCollectionField fieldWithName:@"Current credit"
                                                    andType:VivochaDataCollectionFieldTypeNumber
                                                    andValue:@"39.90"
                                                    andDescription:@"Credit" andIsVisibile:YES andIsChecked:NO]];

VivochaDataCollection *dataCollection = [VivochaDataCollection dataCollectionWithForms:@[form1]];
[Vivocha setDataCollection:dataCollection];

[Vivocha createChatWithDataCollection:[Vivocha getDataCollection] andCompletionBlock:^(VivochaContact *contact) {
    if (contact) {
       [contact showView:YES];
    }
    else{
       //error creating a contact... show an ERROR alert
    }
}];

    Parameters

    dataCollection

    the data collection.
    completionBlock

    returns the created VivochaContact object.

    		 
  • + (void)createWebLeadWithDataCollection:(VivochaDataCollection *)dataCollection
                               andEmail:(NSString *)email
                     andCompletionBlock:
                         (void (^)(VivochaContact *))completionBlock;

    Creates a new weblead.

    Parameters

    dataCollection

    the data collection.
    email

    the Customer’s email
    completionBlock

    returns the created VivochaContact object.

    		 
  • + (void)createCallBackNowWithDataCollection:
            (VivochaDataCollection *)dataCollection
                             andPhoneNumber:(NSString *)phoneNumber
                         andCompletionBlock:
                             (void (^)(VivochaContact *))completionBlock;

    Creates a new CBN (Call Back Now).

    Parameters

    dataCollection

    the data collection.
    phoneNumber

    the Customer’s phone number
    completionBlock

    when the request is completed, the completion block will be execute.

    		 
  • + (void)createVideoChatWithDataCollection:
    (VivochaDataCollection *)dataCollection;

    Creates a new Video Chat contact.

    Parameters

    dataCollection

    the data collection.

    		 
  • + (void)createVideoChatWithDataCollection:
            (VivochaDataCollection *)dataCollection
                       andCompletionBlock:
                           (void (^)(VivochaContact *))completionBlock;

    Creates a new Video Chat contact.

    Parameters

    dataCollection

    the data collection.
    completionBlock

    returns the created VivochaContact object.

    		 
  • + (void)createContactWithDataCollection:(VivochaDataCollection *)dataCollection
                                andType:(NSString *)type
                              andParams:(NSDictionary *)paramsDict
                     andCompletionBlock:
                         (void (^)(VivochaContact *))completionBlock;

    Creates a contact with the given type and parameters.

    Parameters

    dataCollection

    the data collection.
    type

    a string representing the contact type (e.g. “chat”)
    paramsDict

    a dictionary with the parameters needed for the contact creation(e.g. “uri” for type “weblead”)
    completionBlock

    returns the created VivochaContact object.

    		 
  • + (void)setPushTokenWithString:(NSString *)tokenString;

    Enables Vivocha to send push notifications to the current device. If Vivocha was started with automatic set to NO, this method must be called inside the application:didRegisterForRemoteNotificationsWithDeviceToken: method.

    This is a convenience method if you already have the device token converted to NSString.

    Parameters

    tokenString

    the token data received from the application:didRegisterForRemoteNotificationsWithDeviceToken: method and converted to NSString.

    		 
  • + (void)setPushTokenWithData:(NSData *)tokenData;

    Enables Vivocha to send push notifications to the current device. If Vivocha was started with automatic set to NO, this method must be called inside the application:didRegisterForRemoteNotificationsWithDeviceToken: method.

    Parameters

    tokenData

    the token data received from the application:didRegisterForRemoteNotificationsWithDeviceToken: method.

    		 
  • + (void)setBlockSideButton:(BOOL)block;

    Blocks the appearance of the Side Tab button.

    Parameters

    block

    YES if you want to prevent the appearance of the Side button.

    		 
  • - (void)bindAction:(NSString *)actionName
         withBlock:(void (^)(VivochaCustomAction *))block;

    Binds an action name with an action block. When a custom action arrives from the Agent Desktop, the block will be executed and it will have VivochaCustomAction object.

    Usage example:

    [[Vivocha manager] bindAction:@"balanceUpdated" withBlock:^(VivochaCustomAction *action) {
    //The balance was updated from the agent, let's refresh the APP UI

    NSDictionary *payload = [action actionData];

    NSString *balanceValue = [payload objectForKey:@"balance"];

    [MyViewController updateBalanceUIWithValue:balanceValue];
}];

    Parameters

    actionName

    the action name.
    block

    the action block.

    		 
  • - (void)setTappedURLHandler:(BOOL (^)(NSString *))handler;

    Sets a custom handler for URLs that are being tapped by the user inside the chat view. The handler must return YES if the given URL has been handled by the developer, otherwise it will be handled by the chat view.

    Usage example:

    [[Vivocha manager] setTappedURLHandler:^BOOL(NSString *url) {
    if ([url containsString:@"mywebsite.com"]) {

        BOOL handled = [MyApp manageCustomURL:url];

        if (handled) {
            NSLog(@"url handled by MyApp");
            return YES;
        }
    }

    return NO;
}];

    Parameters

    handler

    the URL handler

    		 
  • + (void)setChatHeaderImage:(UIImage *)logoImage;

    Sets a custom logo to be shown in the Chat View in place of the Vivocha one.

    Parameters

    logoImage

    a UIImage object.

    		 
  • + (void)addLocalization:(VivochaLocalization *)localization;

    Adds a new translation to the Vivocha UI. It can be used also to change a string in the supported languages (English and Italian). Translation keys can be found in the VivochaValues header file.

    Usage Example:

        VivochaLocalization *en = [VivochaLocalization localizationWithLanguage:@"en"];
    //Changes the "Agent" string to "Representative"
    [en setTranslation:@"Representative" forKey:VivochaSDK_String_Agent];
    [Vivocha addLocalization:en];

    Parameters

    localization

    the new VivochaLocalization object.

    		 
  • + (NSString *)getVVCU;

    Returns the current VVC-U identifier.

    Return Value

    a string that contains the vvc-u.

  • + (NSString *)getVVCT;

    Returns the VVC-T for the current visit.

    Return Value

    a string that contains the vvc-t.

  • - (void)notifyCustomEngagementButtonShown;

    Notifies Vivocha that a custom-made engagement button as been shown.

  • - (void)notifyCustomEngagementButtonHidden;

    Notifies Vivocha that a custom-made engagement button as been hidden.

  • + (void)storeSurveyWithContactId:(NSString *)contactId
                            data:(VivochaDataCollection *)data
                 completionBlock:(void (^)(NSString *, BOOL))completionBlock;

    Sends the survey result data to Vivocha for the given Contact ID.

    Parameters

    contactId

    the contact ID where attach the survey data to.
    data

    the survey data, as VivochaDataCollection object.
    completionBlock

    the result block that is used to notify success or failure

    		 
  • + (NSString *)getVivochaSDKVersion;

    Return the current VivochaSDK version.