Getting Started

The following sections provide technical details and instructions for setting up a developer's account, integrating the SDK into your own project, and working with the examples and sample apps. Reference documentation for the SDK / Framework is included.

Sandbox Account

  1. Create Your Developer Sandbox Account

    Developer sandboxes are free, they don't expire, and they have enterprise level features enabled. Documents sent in the demo environment are not legally binding and have testing watermarks on them.

  2. Generate Your Integrator Key
  3. An Integrator Key uniquely identifies your app and is also used as your client_id during OAuth token requests. An Integrator Key is needed in order to demo the sample apps, as well as for any of your own test integrations.

    Once you are ready to deploy your application, an Integration Key from your sandbox can be enabled in your live production account. See the go live section for more info.

    To generate an integrator key login to your sandbox, click the profile icon in the top right, and select Go To Admin.

    On the lower left side of the Admin Console select API and Keys then click the Add Integrator Key button:

    Enter a description and click ADD to create a new Integrator Key. You'll want to take note of the Integrator Key value, as this will be needed to setup the SDK and/or sample apps. This same value is used as your client_id during the OAuth authorization flow.

SDK Core Interfaces

Below is a list of the core interface methods you will need while using the iOS SDK framework.

SDK Initialization During Application Launch

This setup call ensures that Core Data is set up for the SDK.

This method is available via DSMManager.h. Please see the Tech Docs section for more information.

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
	[DSMManager setup];
	return YES;
}
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
	DSMManager.setup()
	return true
}

Log In and User Setup

This setup can be done when the user logs in to the client application. The loginWithUserId method accepts the user name and password of a DocuSign user. The integrator key uniquely identifies your client application. The Host parameter specifies which server the user should use to register (e.g. NA1, NA2, Demo, etc.).

This method is available via DSMManager.h. Please see the Tech Docs section for more information.

If you do not already have a user account and integrator key, you can sign up for a DocuSign Developer Account and create an integrator key via the DocuSign admin portal.

[DSMManager loginWithUserId:*NSString 
	password:*NSString 
	integratorKey:*NSString 
	host:[NSURL URLWithString:*NSString] 
	completionBlock:^(NSError *error) {
	...
}];
DSMManager.login(withUserId: String!, 
	password: String!, 
	integratorKey: String!, 
	host: URL!, 
	completionBlock: ((Error?) -> Void)! {
	...
	})

Template Caching

Templates created through the DocuSign web portal can be downloaded and cached to a device for use offline later on. Templates are identified by an ID which is passed to the cacheTemplateWithId method. Templates may be comprised of documents, recipients, and tabs / custom data fields.

This method is available via DSMTemplatesManager.h. Please see the Tech Docs section for for information.

[templatesManager cacheTemplateWithId:*NSString 
	completion:^(NSError *error) {
	...
}];
DSMTemplatesManager.cacheTemplate(withId: String!,
	completionBlock: ((Error?) in Void)! {
	...
	}
)

Template Sending and Signing

This method initiates the signing process with the specified template. The signingMode parameter (DSMSigningModeOnline/DSMSigningModeOffline) indicates whether the SDK should use the online flow via the web portal or capture the signature using the offline signing flow. The presentingController parameter is the client ViewController that will be used to present the SDK signing screens.

This method is available via DSMTemplatesManager.h. Please see the Tech Docs section for more information.

[templatesManager presentSendTemplateControllerWithTemplateWithId:*NSString 
	signingMode:DSMSigningMode 
	presentingController:*UIViewController 
	animated:BOOL 
	completion:void(^)(UIViewController *viewController, NSError *error) { 
	...
	}
];
DSMTemplatesManager.presentSendTemplateControllerWithTemplate(withId: String!, 
	signingMode: DSMSigningMode, 
	presenting: UIViewController, 
	animated: Bool, 
	completionBlock: ((UIViewController, Error?) in Void)! {
	...
	}
)

Custom Data and PDF Insert

The SDK allows you to map client-data to custom fields within the template using the envelopeDefaults parameter. In addition, an external PDF document may be included in the envelope and will be displayed either before or after the template document(s) based on the insertAtPosition parameter (which defaults to DSMDocumentInsertAtPositionBeginning). The presentingController parameter is the client ViewController that will be used to present the SDK screens.

This method is available via DSMTemplatesManager.h and DSMDocumentInsertAtPosition is available in DSMDocumentInsertAtPosition.h. Please see the Tech Docs section for more information.

[templatesManager presentSendTemplateControllerWithTemplateWithId:*NSString 
	envelopeDefaults:*DSMEnvelopeDefaults 
	pdfToInsert:*NSData 
	insertAtPosition:DSMDocumentInsertAtPositionBeginning 
	onlineSigning:BOOL 
	presentingController:*UIViewController 
	animated:BOOL 
	completion:void(^)(UIViewController *viewController, NSError *error) { 
	...
	}
];
DSMTemplatesManager.presentSendTemplateControllerWithTemplate(withId: String!, 
	envelopeDefaults: DSMEnvelopeDefaults, 
	pdfToInsert: Data!, 
	insertAtPosition: DSMDocumentInsertAtPosition, 
	onlineSigning: Bool, 
	presenting: UIViewController, 
	animated: Bool, 
	completionBlock: ((UIViewController, Error?) in Void)! {
	...
	}
)

Envelope Creation and Signing

This method initiates the envelope creation process (adding documents, recipients, and tags) without previously downloading any templates. The presentingController parameter is the client ViewController that will be used to present the SDK signing screens. The signingMode parameter (DSMSigningModeOnline/DSMSigningModeOffline) will determine the behaviour once the envelope is created, which would either use the online flow via the web portal or capture the signature using the offline signing flow. The resumeWithDraft parameter specifies whether to a continue a previously saved incomplete envelope.

This method is available via DSMEnvelopesManager.h. Please see the Tech Docs section for more information.

[envelopesManager presentComposeEnvelopeControllerWithPresentingController:*UIViewController 
	signingMode:DSMSigningMode
	resumeWithDraft:BOOL
	animated:BOOL
	completion:(void(^)(UIViewController *viewController)) {
	...
	}
];
envelopesManager.presentComposeEnvelopeController(withPresenting: UIViewController, 
	signingMode: DSMSigningMode, 
	resumeWithDraft: Bool, 
	animated: Bool, 
	completionBlock: ((UIViewController) in Void)! {
	...
	}
)

Data Model Diagram

Compose Envelope Flow

Integration Steps

The following describes how to import and configure the Native iOS Offline Templates SDK into your XCode project. The steps are the same for both Objective-C and Swift projects.

  1. Download the DocuSignSDK.framework

  2. Download the framework file, and then drag and drop it into your XCode project.

  3. Within your Xcode project, navigate to Target > General settings and under Embedded Binaries, add the DocuSignSDK.framework.

  4. Navigate to Target > Build Phases and under Copy Bundle Resource -> DocuSignSDK.bundle.

    These bundle files can be found within the DocuSignSDK.framework folder. Use the Add Other button, at bottom-left, to navigate into the framework folder.

  5. Also in Target > Build Phases, add a new Run Script Phase.

    IMPORTANT! Be sure this Run Script Phase is located below the Embed Frameworks build phase. You can drag-and-drop build phases to rearrange them.

    Paste the following line into the new Run Script Phase script text field:

    bash "$BUILT_PRODUCTS_DIR/$FRAMEWORKS_FOLDER_PATH/DocuSignSDK.framework/strip-frameworks.sh"

  6. Within your project's Info.plist file, set values for the following keys:

    KEYS VALUES
    Privacy - Camera Usage Description $(PRODUCT_NAME) camera use
    Privacy - Contacts Usage Description $(PRODUCT_NAME) contact use
    Privacy - Location When In Use Usage Description $(PRODUCT_NAME) location use

    Currently, the SDK uses these permissions as follows:

         CAMERA: Used when taking a picture of a hand-written signature

         CONTACT: Used to retrieve recipient details from the device's address book to use while sending templates

         LOCATION: Used to record the device's location while signing a document

  7. Build and run the app.

    Note: You may experience the following issue with the build:

    Linker command failed with exit code 1

    One possibility is a Bitcode-related issue. Navigate to the project's Build Settings > Build Options and set the Enable Bitcode property to No, and then attempt to rebuild the project.

Objective-C Sample App

The Allura Insurance sample app is an iOS Objective-C application developed for a fictional insurance company that demonstrates most aspects of integration, online and offline signing use of the DocuSign Native iOS Offline Templates SDK.

Please follow the steps below to download, configure and run the sample app.

  1. If you have not already, create a developer sandbox account and create an Integrator Key. See the Getting Started section for more details.

  2. Download the Allura Insurance sample app from GitHub: docusign-sdk-sample-objc

  3. Run pod install

  4. Copy DocuSignSDK.framework to root directory of Sample Application

  5. Locate the Allura-Template.pdf file inside the project's root folder. This document will serve as the base for the template we will create in your developer sandbox account.

  6. Log into your DocuSign Developer sandbox account and navigate to the Templates tab.

  7. Click New and Create Template, then give the new template a name. A description may also be added, but is not required.

  8. Upload the Allura-Template.pdf file.

  9. Add the email you used for your developer's account as a recipient and include your name. A role may also be added, but is not required.

    Ensure the drop-down to the right reads Needs to Sign and then click Add Recipient.

  10. Click the NEXT button in the upper-right corner.

  11. The following screen loads the PDF that was uploaded and allows us to drag-and-drop custom data fields on the document that will be populated at runtime.

    We will add 5 text fields and a signature field, as shown in the screenshot below.

  12. Select one of the text fields and expand the Data Label property on the right side menu. Each custom field is assigned a unique data label ID that can be used to map client-data originating from the app.

    Select each of the 5 text fields we added above, and take note of their Data Label IDs. They will be needed shortly.

  13. Click the SAVE AND CLOSE button in the upper-right corner. We have just successfully created our template file.

  14. Open "docusign-sdk-sample-objc.xcworkspace" in XCode 8 or later.

  15. Under the Managers group, navigate to the ProfileManager.m class file and update the integratorKey variable. Optionally you can include your developer sandbox username and password that will pre-populate on the login screen.

  16. Also in the ProfileManager.m class, locate the 5 tabKey_***** variables. These correspond to the 5 custom text fields we added to the template we created. Update these variables with the Data Label ID values we gathered from the template.

  17. Build and run the app.

    Note: You may experience the following issue with the build:

    Linker command failed with exit code 1

    One possibility is a Bitcode-related issue. Navigate to the project's Build Settings > Build Options and set the Enable Bitcode property to No, and then attempt to rebuild the project.

Swift Sample App

The TGK Capital Financial sample app is an iOS Swift 3.0 application developed for a fictional finance company that demonstrates most aspects of integration, online and offline signing use of the DocuSign Native iOS Offline Templates SDK.

Please follow the steps below to download, configure and run the sample app.

  1. If you have not already, create a developer sandbox account and create an Integrator Key. See the Getting Started section for more details.

  2. Download the TGK Capital Financial sample app from GitHub: docusign-sdk-sample-swift

  3. Run pod install

  4. Copy DocuSignSDK.framework to root directory of Sample Application

  5. Locate the TGK-Capital-Template.pdf file inside the project's root folder. This document will serve as the base for the template we will create in your developer sandbox account.

  6. Log into your DocuSign Developer sandbox account and navigate to the Templates tab.

  7. Click New and Create Template, then give the new template a name. A description may also be added, but is not required.

  8. Upload the TGK-Capital-Template.pdf file.

  9. Add the email you used for your developer's account as a recipient and include your name. A role may also be added, but is not required.

    Ensure the drop-down to the right reads Needs to Sign and then click Add Recipient.

  10. Click the NEXT button in the upper-right corner.

  11. The following screen loads the PDF that was uploaded and allows us to drag-and-drop custom data fields on the document that will be populated at runtime.

    We will add 6 text fields and a signature field, as shown in the screenshot below.

  12. Select one of the text fields and expand the Data Label property on the right side menu. Each custom field is assigned a unique data label ID that can be used to map client-data originating from the app.

    Select each of the 6 text fields we added above, and take note of their Data Label IDs. They will be needed shortly.

  13. Click the SAVE AND CLOSE button in the upper-right corner. We have just successfully created our template file.

  14. Open "docusign-sdk-sample-swift.xcworkspace" in XCode 8 or later.

  15. Under the Managers group, navigate to the ProfileManager.swift class file and update the integratorKey variable. Optionally you can include your developer sandbox username and password that will pre-populate on the login screen.

  16. Also in the ProfileManager.swift class, locate the 6 tabKey_***** variables. These correspond to the 6 custom text fields we added to the template we created. Update these variables with the Data Label ID values we gathered from the template.

  17. Build and run the app.

    Note: You may experience the following issue with the build:

    Linker command failed with exit code 1

    One possibility is a Bitcode-related issue. Navigate to the project's Build Settings > Build Options and set the Enable Bitcode property to No, and then attempt to rebuild the project.