Onespan Sign Ios SDK Integrator's Guide
Total Page:16
File Type:pdf, Size:1020Kb
NOTE: This PDF is no longer being maintained. For the latest updates, please refer to our Community Portal. OneSpan Sign iOS SDK Integrator's Guide Date: January 28, 2020 Version: OneSpan Sign 7.2 Copyright Notices Copyright © 2019 OneSpan North America, Inc. All rights reserved. Trademarks OneSpan™, DIGIPASS® and CRONTO® are registered or unregistered trademarks of OneSpan North America Inc. and/or OneSpan International GmbH (collectively "OneSpan") in the U.S. and other countries. OneSpan reserves all rights to the trademarks, service marks and logos of OneSpan and its subsidiaries. All other trademarks or trade names are the property of their respective owners. Intellectual Property OneSpan Software, documents and related materials (“Materials”) contain proprietary and confidential information. All title, rights and interest in OneSpan Software and Materials, updates and upgrades thereof, including software rights, copyrights, patent rights, industrial design rights, trade secret rights, sui generis database rights, and all other intellectual and industrial property rights, vest exclusively in OneSpan or its licensors. No OneSpan Software or Materials may be downloaded, copied, transferred, disclosed, reproduced, redistributed, or transmitted in any form or by any means, elec- tronic, mechanical or otherwise, for any commercial or production purpose, except as otherwise marked or when expressly permitted by OneSpan in writing. Disclaimer OneSpan accepts no liability for the accuracy, completeness, or timeliness of content, or for the reliability of links to and content of external or third party websites or materials. OneSpan shall have no liability under any circumstances for any loss, damage, or expense incurred by you, your com- pany, or any third party arising from the use or inability to use OneSpan Software or Materials, or any third party mater- ial made available or downloadable. OneSpan will not be liable in relation to any loss/damage caused by modification of these Legal Notices or content. Reservation OneSpan reserves the right to modify these Notices and the content at any time. OneSpan likewise reserves the right to withdraw or revoke consent or otherwise prohibit use of the OneSpan Software or Materials if such use does not con- form to the terms of any written agreement between OneSpan and you, or other applicable terms that OneSpan pub- lishes from time to time. Contact us Phone: 1-855-MYESIGN e-Mail: [email protected] Customer Support: https://www.esignlive.com/customer-support Resource center: https://www.esignlive.com/resource-center Company Website: https://www.onespan.com Date: January 28, 2020 CONTENTS 1 Introduction 1 1.1 Server-Side Software 2 2 Client-Side Software 3 2.1 Client-Side Packaging 4 2.2 Integrating the OneSpan Sign iOS SDK 6 2.3 Using Interfaces 8 3 Code Examples 9 3.1 Initial Configuration 10 3.2 Login 12 3.3 Signup 13 3.4 Loading a Transaction from the Server 14 3.5 Creating/Preparing a Transaction 15 3.6 Creating a Transaction and Starting to Sign 16 3.7 Getting a List of Transactions 19 3.8 Creating a Navigation Controller Stack 20 4 Troubleshooting 21 4.1 Error Linking Swift Libraries 22 4.2 PDF Header Not Found 23 4.3 Delegate Not Found 24 iii eSignLive iOS SDK - Integrator's Guide 4.4 Failure to Load Fonts 25 4.5 Invalid Certificate 26 4.6 PLBuildVersion Warning 27 4.7 Crash When Accessing Contacts 28 iv eSignLive iOS SDK - Integrator's Guide Introduction 1 The OneSpan Sign iOS SDK is a feature that enables users to run e-signature pro- cesses from mobile devices that use iOS 10 and higher. This SDK employs a server-client model, with a OneSpan Sign product as "server" and a company's mobile application as "client". The server can be either a SaaS product (e.g., OneSpan Sign Professional) or an on-premises product (e.g., OneSpan Sign). Because of this server-client model, this feature won't work until both of the fol- lowing have been configured: l Server-Side Software on page 2 l Client-Side Software on page 3 For any issues see Troubleshooting on page 21 NOTE: Strictly speaking, the OneSpan Sign iOS SDK is only on the client side. The role of the server side is to provide support for the OneSpan Sign iOS SDK. Download the OneSpan Sign iOS SDK. TIP: To view Release Notes for the OneSpan Sign iOS SDK, click here. 1 Introduction 1 eSignLive iOS SDK - Integrator's Guide 1.1 Server-Side Software Signing on mobile devices via the OneSpan Sign iOS SDK will not work unless sup- porting server-side software has been provided. That server-side software becomes available as soon as you create your SaaS account. 1 Introduction 2 eSignLive iOS SDK - Integrator's Guide Client-Side Software 2 This section discusses: l Client-Side Packaging on page 4 l Integrating the OneSpan Sign iOS SDK on page 6 l Using Interfaces on page 8 l Code Examples on page 9 2 Client-Side Software 3 eSignLive iOS SDK - Integrator's Guide 2.1 Client-Side Packaging Each release of the OneSpan Sign iOS SDK has an eSignLiveSDK_iOS directory, which in turn has the following main sub-directories: 1. Sample: Contains a sample project that provides a detailed demonstration of the following SDK functionalities: l Login (with email and password) l Start/Edit Transaction l Prepare New Transaction 2. Frameworks: Contains the following sub-folders: l Debug-universal: Contains a Debug Framework for the fol- lowing architectures: arm7, arm7s, arm64, i386 and x86_64 (for both Device and Simulator) l Release-iphoneos: Contains a Release Framework for the fol- lowing ARM architectures: arm7, arm7s, and arm64 3. SDKAssets: Contains the following sub-folders: l Fonts: Contains the font files to be added to the project target and to the file info.plist. l Images: Contains SDK-used images in an asset file. Any image can be replaced by another if it has the same name and res- olution. l UIElements: Contains storyboard files and NIB files, both of which are used to build a User Interface. These files can be edited as needed. NOTE: The above SDK Assets are not compiled with the SDK, but are linked via the end-developer application. 2 Client-Side Software 4 eSignLive iOS SDK - Integrator's Guide End-developers may customize these assets to suit their needs. 2 Client-Side Software 5 eSignLive iOS SDK - Integrator's Guide 2.2 Integrating the OneSpan Sign iOS SDK This section discusses: l Integrating the OneSpan Sign iOS SDK Framework into an Existing Project on page 6 l Non-Native iOS Applications on page 7 NOTE: The Sample project has already been integrated with the Debug Framework. Please integrate the Release Framework before submitting your application to the App Store. 2.2.1 Integrating the OneSpan Sign iOS SDK Framework into an Existing Project 1. Open your project in Xcode, and select it from the Project Navigator. 2. Select the appropriate target from the TARGETS panel, and click the General tab. 3. Scroll down to Embedded Binaries. 4. Drag and drop the Framework file called eSignLiveSDK.framework into Embed- ded Binaries. 5. In the dialog box that appears, select Copy items if needed. 6. Click Finish. The Framework file eSignLiveSDK.framework will be added to: l Embedded Binaries l Linked Frameworks and Libraries l Project Navigator 7. Click the Build Settings tab, and set Always Embed Swift Standard Libraries = 2 Client-Side Software 6 eSignLive iOS SDK - Integrator's Guide YES. In the previous version of Xcode, this flag was called EMBEDDED_CONTENT_ CONTAINS_SWIFT. 8. Drag the SDKAssets folder from the eSignLiveSDK_iOS directory, and drop it into the Project Navigator. 9. In the dialog box that appears, select Copy items if needed and Add to targets. 10. Click Finish. 11. To properly configure the file info.plist: a. Open the file info.plist. b. If it is not already there, add the property Fonts provided by application. This property is called UIAppFonts in raw format. c. Add an item for each font you want to support. d. Add the following font values: Ubuntu-Bold.ttf, Ubuntu-Italic.ttf, Ubuntu- Regular.ttf, Ubuntu-Light.ttf. e. If it is not already there, add the property Privacy - Contacts Usage Description., and type a description of how the application will use its Contacts data. This property is called NSContactsUsageDescription in raw format. f. Save and close the file info.plist. 12. Ensure that the "code signing" properties are configured correctly. 13. Clean, build and run your project. There should be no Compiler or Linker errors at this stage. 2.2.2 Non-Native iOS Applications Non-native applications (built over third-party implementations) can integrate the OneSpan Sign Mobile SDK into their application. However, hooks to the SDK must be added through delegate Callbacks of UIWebview or UIWebKit. A navigation con- troller reference must be provided for push stack. 2 Client-Side Software 7 eSignLive iOS SDK - Integrator's Guide 2.3 Using Interfaces The Headers sub-directory of eSignLiveSDK.framework includes the following inter- faces: l eSignLiveSDK.h — The umbrella header l OneSpan Sign.h — Most integration work involves this interface. l ESTransaction.h — A representation of a Transaction interface object l ESDocument.h — A representation of a Document interface object l ESFormfield.h — A representation of a Form Field interface object l ESSigner.h — A representation of a Signer interface object Detailed documentation of each interface is in the file that bears its name. To see how these interfaces are used: 1. Go to the Sample project provided by OneSpan Sign. 2. Open the file ViewController.m, which contains code snippets for the most important SDK features.