SigningHub iOS SDK Integration

The "iOS SDK Integration" page is intended for developers who are interested in writing applications which will use the capabilities offered by SigningHub Mobile SDK. It is assumed that the reader has a basic knowledge of iOS and JSON.

Overview

The SigningHub iOS SDK is built on top of our REST-based API web services. This SDK is a quick way to integrate SigningHub with different mobile applications. SigningHub Mobile SDK provides the following features:

  • Document preparation

    • Upload documents from local files, library, and cloud drives (Google Drive, OneDrive, and Dropbox)

    • Add, update, and delete recipients (contact, group, placeholder, electronic seal)

    • Add signature fields (digital signature, electronic signature, In-person signature, initials)

    • Add form fields (input field, check box, radio box)

    • Add attachment field

    • Add QR code

    • Add drop-in comment

  • Access authentication (shared password, OTP, TOTP)

  • Access duration (based on dates, based on days)

  • Document viewing

    • Draft

    • In-Progress

    • Pending

    • Signed

    • Declined

    • Approved

    • Updated

    • Completed

  • Form filling

    • Text field

    • Check box

    • Radio button

    • Drop down, etc.

  • Adding initials

  • Signing In-person

  • Electronic signature (with or without witness signature)

  • Legal notice

  • Server-side signing authentication

  • Signing using a hand-drawn image, an uploaded image (via photo gallery) or text-based typography (using a fixed embedded font)

  • Document signing (digital signature)

  • Authorise remote signing for a qualified signature

  • View existing signatures and verification details

  • Declining a document

  • Approving a document

  • Editing a document

  • Branding

  • Localization

SigningHub Mobile SDK prerequisites

To integrate the SigningHub SDK, the integrated iOS application should meet the following prerequisites:

  • iOS application deployment target 13.0 or above.

  • Xcode 15.0 or above.

  • Navigation controller-based iOS application.

Add SigningHub SDK to an iOS application project

To use the SigningHub SDK in an iOS application project, follow the steps below:

  1. Go to Xcode > New Project > Select a New Project.

  2. After you create a new project, go to the project target and add “SigningHubSDK”, “GoSignMobileSDK”, and “CryptoAPI” frameworks into the Embedded Libraries as shown in the following screenshot.

  3. After adding frameworks, drag “SigningHubResourceBundle” into your project.

  4. Set 'User Script Sandboxing' to ‘No’ in the project settings.

  5. Set 'Always Embed Swift Standard Libraries' to ‘YES’.

  6. SigningHubSDK has the following dependencies of Pods:

    • pod 'ADAL', '~> 4.0.11'

    • pod 'Material', '~> 3.1.0'

    • pod 'MaterialComponents'

    • pod 'KeyClip'

    • pod 'KISnackBar'

    • pod 'Firebase/DynamicLinks '

    • pod 'Firebase/Core'

    • pod 'Firebase/Messaging'

    • pod 'Firebase/Crashlytics'

    • pod 'FirebasePerformance'

    • pod 'FirebaseCoreDiagnostics'

    • pod 'SwiftLint'

    • pod 'AlamofireImage', '~> 4.1', :modular_headers => true

    • pod 'DropDown'

    • pod 'IQKeyboardManager'

    • pod 'Shimmer', '~> 1.0.2'

    • pod 'CMPopTipView'

    • pod 'Kingfisher', '~> 8.3'

    • pod 'AFNetworking', '~> 2.5.4', :subspecs => ['Reachability', 'Serialization', 'Security', 'NSURLSession', 'NSURLConnection'] //For Go>Sign SDK

    • pod 'JOSESwift', '~> 2.3' 

      # This forces all installed CocoaPods dependencies to use iOS 13.0 
# as the minimum deployment target.
post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '13.0'
      config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
    end
  end
end

  7. Open Info.plist of your project in a text editor, and add the following lines:

<key>NSCameraUsageDescription</key>
    <string>Allow camera access to select a hand signature image</string>
    <key>NSFaceIDUsageDescription</key>
    <string></string>
    <key>NSPhotoLibraryUsageDescription</key>
    <string>This app requires access to the photo library.</string>
    <key>UIAppFonts</key>
    <array>
        <string>susie.ttf</string>
        <string>soljik-dambaek.ttf</string>
        <string>scriptin.ttf</string>
        <string>GloriaHallelujah-Regular.ttf</string>
        <string>Mr Dafoe.ttf</string>
        <string>Palatino Linotype.ttf</string>
        <string>phontphreaks.ttf</string>
        <string>Inter-Black.ttf</string>
        <string>Inter-Bold.ttf</string>
        <string>Inter-ExtraBold.ttf</string>
        <string>Inter-ExtraLight.ttf</string>
        <string>Inter-Light.ttf</string>
        <string>Inter-VariableFont_slnt,wght.ttf</string>
        <string>Inter-Thin.ttf</string>
        <string>Inter-SemiBold.ttf</string>
        <string>Inter-Regular.ttf</string>
        <string>Inter-Medium.ttf</string>
        <string>Barlow-ThinItalic.ttf</string>
        <string>Barlow-Thin.ttf</string>
        <string>Barlow-SemiBoldItalic.ttf</string>
        <string>Barlow-SemiBold.ttf</string>
        <string>Barlow-Regular.ttf</string>
        <string>Barlow-MediumItalic.ttf</string>
        <string>Barlow-Medium.ttf</string>
        <string>Barlow-LightItalic.ttf</string>
        <string>Barlow-Light.ttf</string>
        <string>Barlow-Italic.ttf</string>
        <string>Barlow-ExtraLightItalic.ttf</string>
        <string>Barlow-ExtraLight.ttf</string>
        <string>Barlow-ExtraBoldItalic.ttf</string>
        <string>Barlow-ExtraBold.ttf</string>
        <string>Barlow-BoldItalic.ttf</string>
        <string>Barlow-Bold.ttf</string>
        <string>Barlow-BlackItalic.ttf</string>
        <string>Barlow-Black.ttf</string>
        <string>SFPRODISPLAYULTRALIGHTITALIC.OTF</string>
        <string>SFPRODISPLAYTHINITALIC.OTF</string>
        <string>SFPRODISPLAYSEMIBOLDITALIC.OTF</string>
        <string>SFPRODISPLAYREGULAR.OTF</string>
        <string>SFPRODISPLAYMEDIUM.OTF</string>
        <string>SFPRODISPLAYLIGHTITALIC.OTF</string>
        <string>SFPRODISPLAYHEAVYITALIC.OTF</string>
        <string>SFPRODISPLAYBOLD.OTF</string>
        <string>SFPRODISPLAYBLACKITALIC.OTF</string>
    </array>

Integrate SigningHub SDK in the business application

The business application needs to import the following header file in its code:

  • import SigningHubSDK

The SigningHubSDK authenticates the user who is registered in the SigningHub and then provides the supported features.

Authentication

Manages user authentication and session-related operations. This class provides a high-level abstraction for handling authentication.

This class provides authentication functionality for SigningHub using both password-based and Single Sign-On (SSO) methods. It also supports user logout and session validation. Additionally, it includes utility methods for checking authentication status and retrieving tokens required by the SigningHub SDK

Features

This class offers the following key features to support secure and seamless authentication:

  • Token Management: Fetch client tokens, refresh access tokens, and manage authentication tokens.

  • User Authentication: Authenticate users via password or Single Sign-On (SSO).

  • Session Management: Check authentication status, retrieve access tokens, and log out users.

  • API Base URL Management: Update and retrieve the API base URL dynamically.

  • Error Handling: Robust error handling with detailed error messages.

Class structure

The SessionManager class with the following key methods:

  • authenticateWithPassword: Authenticates a user using their email and password.

  • authenticateWithSSO: Authenticates a user via Single Sign-On (SSO).

  • logout: Logs out the user and clears authentication data.

  • isAuthenticated: Checks if the user is authenticated.

  • fetchClientToken: Fetches a client token for initial authentication.

  • accessToken: Retrieves the current access token.

Authentication with a password

SigningHubSDK has a class “SessionManager” that is used for the authentication of a user. Following is the code for user authentication.

let sessionManager = SessionManager()

sessionManager.authenticateWithPassword(
    url: url,
    email: email,
    password: password,
    headerParams: [:]
) { response, statusCode, success, responseHeaders in }
Parameter
Description

url

The URL where the SigningHub API Server is deployed.

email

The email address of the user.

password

The password of the user.

headerParams

Optional dictionary containing additional header parameters.

Authentication callback

The authentication method triggers events for success and failure. The business application must implement the CallBackListener in the business application controller. Here is the response:

  • response: The data returned from the server.

  • statusCode: The HTTP status code of the response.

  • success: Boolean indicating authentication success.

  • responseHeaders: A dictionary containing response headers.

{ response, statusCode, success, responseHeaders in
    DispatchQueue.main.async {
        if success {
            print(“success”)
        } else {
            Print(“failure”)
        }
    }
}

On success, the authentication delegate receives the following information:

  • accessToken

  • refreshToken

  • tokenType

  • expiryTime

Authentication via SSO

SigningHubSDK has a class “SessionManager” that is used for the authentication of a user with SSO. The application can call this method to get the access token of a user by requesting a third party, based on the provided method and token. Currently supported third parties are Office 365, Azure Active Directory, OAuth2 and OIDC. Following is the code for user authentication.

let sessionManager = SessionManager()

sessionManager.authenticateWithSSO(
    url: url,
    code: code,
    token: token,
    authMethod: method,
    profileName: profile,
    headerParams: [:]
) { response, statusCode, success, responseHeaders in }
Parameter
Description

url

The URL where the SigningHub API Server is deployed.

code

Authorization code obtained from OAuth2/OIDC.

token

Token from a third-party provider (e.g., Office 365, Azure AD, OAuth2, OIDC).

authMethod

The authentication method type (e.g., "OFFICE_365", "AZURE_ACTIVE_DIRECTORY", "OAUTH2", "OIDC").

profileName

Required for "OAUTH2" and "OIDC". Alternative to profile_id.

headerParams

Optional dictionary containing additional header parameters.

Authentication with SSO callback

The authentication method triggers events for success and failure. The business application must implement the CallBackListener in the business application controller. Here is the response:

  • response: The data returned from the server.

  • statusCode: The HTTP status code of the response.

  • success: Boolean indicating authentication success.

  • responseHeaders: A dictionary containing response headers.

{ response, statusCode, success, responseHeaders in
    DispatchQueue.main.async {
        if success {
            print(“success”)
        } else {
            Print(“failure”)
        }
    }
}

On success, the authentication delegate receives the following information:

  • accessToken

  • refreshToken

  • tokenType

  • expiryTime

Logout

Logs out the user and clears all authentication-related data.

let sessionManager = SessionManager()

self.authManager.logout(completion: { response, statusCode in
    DispatchQueue.main.async {
    }
})

User authentication

This method verifies whether the user is currently authenticated

Returns: `true` if the user has a valid access token, otherwise `false`.

let sessionManager = SessionManager()

if (self.authManager.isAuthenticated()) {
}

Fetch client token

This method retrieves the client access token required for API authentication

Returns: A `String` representing the client token if available, otherwise `nil`.

let sessionManager = SessionManager()

if (self.authManager.fetchClientToken()) {
}

Fetch user token

This method retrieves the user's access token and returns the updated token

Returns: A `String` representing the access token if available, otherwise `nil`.

let sessionManager = SessionManager()

if (self.authManager.accessToken()) {
}

Open document

Once the authentication is done, document opening can be handled via the DocumentManager class.

Overview

The DocumentManager class is a utility object provided by the SigningHub SDK to manage document-related workflows. It simplifies the process of creating, cloning, and opening workflows for actions such as signing or reviewing documents. This class serves as the primary entry point for interacting with the SDK's workflow management features.

Key Features:

  • Workflow Initialisation: Start new workflows from scratch or by cloning existing packages.

  • Workflow Management: Open existing workflows for actions like signing or reviewing.

  • Efficient Workflow Handling: Pre-fetched workflow details can be used to avoid redundant API calls.

Class structure

The DocumentManager class is a singleton object with the following key methods:

  • startNewWorkFlow: Starts a new workflow from scratch.

  • openPackageViewer: Opens an existing workflow for actions like signing or reviewing.

Start new workflow

Starts a new workflow from scratch with default SigningHub settings.

Parameters:

  • navigationControllerReferance: The navigation controller that will push the new workflow screen onto the stack.

let documentManager = DocumentManager()

documentManager.startNewWorkFlow(
    navigationControllerReferance: self.navigationController!
)

Open package viewer

Opens an existing workflow for actions such as signing or reviewing.

Parameters:

  • navigationControllerReferance: The navigation controller that will push the package viewer onto the stack.

  • packageId: The unique identifier of the package to be viewed. (required)

func moveToDocumentViewer(packageId: Int) {
    let documentManager = DocumentManager()
    
    documentManager.openPackageViewer(
        navigationControllerReferance: self.navigationController!,
        packageId: packageId
    )
}

Branding

Branding in SigningHubSDK allows customisation of the app's appearance using different colour levels. The backend provides the following branding:

  • Admin Branding – Applied globally across all enterprises.

  • Enterprise Branding – Custom branding per enterprise.

Developers can retrieve branding settings using the REST APIs provided by SigningHub. The SDK automatically applies branding when provided with valid colour data for branding.

Colour level usage in the app

  • Level 1: Primary button background (used for main action buttons).

  • Level 2: Content displayed on Level 1 colour (text colour).

  • Level 3: Negative actions (e.g., Delete, Remove, Logout).

  • For filled negative buttons, Level 3 is the background colour.

  • For outlined/text buttons, Level 3 is the text/icon colour.

let documentManager = DocumentManager()

DocumentManager.brandingColors.setLevelOneColor(hexCodeString: "adb5bd")
DocumentManager.brandingColors.setLevelTwoColor(hexCodeString: "ffffff")
DocumentManager.brandingColors.setLevelThreeColor(hexCodeString: "e03500")

Example project on Bitbucket

To help developers get started quickly, we provide an example project hosted on Bitbucket. This project demonstrates how to integrate and use the SigningHub SDK within an iOS application.

Repository URL: SigningHub SH10 SDK Example

  1. The SigninghubSDK and GoSignMobileSDKfiles are not included in the example project due to licensing. You must add your own, as explained above, inside the SH&GoSignSDK folder to successfully run the project.

PreviousSigningHub Android SDK IntegrationNextGo>Sign Mobile SDK Integration

Last updated

Was this helpful?