Launches the recipient (signer) view of an envelope in an embedded session

EmbeddedSigning.m

//
//  API Walkthrough 8 - Launch the signing (recipient) view of an envelope in an embedded session
//
//  To run this sample:
//      1.  Copy the below code into your iOS project
//      2.  Enter your email, password, integrator key, name, templateId, and roleName and save
//      3.  Run the code
//

// Enter your info:
NSString *email = @"<#email#>";
NSString *password = @"<#password#>";
NSString *integratorKey = @"<#integratorKey#>";
NSString *name = @"<#name#>";

// use same name as template role you saved through the Console UI
NSString *roleName = @"<#roleName#>";

// need to login to the console and copy a valid templateId into this string
NSString *templateId = @"<#templateId#>";
 
// To add Embedded recipients to an envelope you must set their |clientUserId| property.
// This is a client-configurable string value (i.e. can be "1", "1001", "1a2b3c", etc.)
NSString *clientUserId = @"<#clientUserId#>";

- (void)embeddedSigning
{
    ///////////////////////////////////////////////////////////////////////////////////////
    // STEP 1 - Login (retrieves accountId and baseUrl)
    ///////////////////////////////////////////////////////////////////////////////////////
    
    // endpoint for the Login api
    NSString *loginURL = @"https://demo.docusign.net/restapi/v2/login_information";
    
    // initialize a request object with the following url, method, and body (no body for login api call)
    NSMutableURLRequest *loginRequest = [self initializeRequest:loginURL setMethod:@"GET" setBody:nil];
    
    // add content-type and authorization headers
    [self addRequestHeaders:loginRequest];
    
    //--> make an asynchronous web request
    [NSURLConnection sendAsynchronousRequest:loginRequest queue:[NSOperationQueue mainQueue] completionHandler:^(NSURLResponse *loginResponse, NSData *loginData, NSError *loginError) {
        
        // create NSDictionary out of JSON data that is returned
        NSDictionary *responseDictionary = [self getHttpResponse:loginRequest response:loginResponse data:loginData error:loginError];
        if( responseDictionary == nil)
            return;
        
        // parse the accountId and baseUrl from the response and use in the next request
        NSString *accountId = responseDictionary[@"loginAccounts"][0][@"accountId"];
        NSString *baseUrl = responseDictionary[@"loginAccounts"][0][@"baseUrl"];
        
        //--- display results
        NSLog(@"\naccountId = %@\nbaseUrl = %@\n", accountId, baseUrl);
        
        ///////////////////////////////////////////////////////////////////////////////////////
        // STEP 2 - Create Envelope via Template and send the envelope
        ///////////////////////////////////////////////////////////////////////////////////////
        
        // construct a JSON formatted signature request body (multi-line for readability)
        NSDictionary *signatureRequestData = @{@"accountId": accountId,
                                               @"emailSubject" : @"Embedded Sending API call",
                                               @"emailBlurb" : @"email body goes here",
                                               @"templateId" : templateId,
                                               @"templateRoles" : [NSArray arrayWithObjects: @{@"email":email, @"name": name, @"roleName": roleName, @"clientUserId": clientUserId }, nil ],
                                               @"status" : @"sent"
                                               };
        
        // convert request body into an NSData object
        NSData* data = [[self jsonStringFromObject:signatureRequestData] dataUsingEncoding:NSUTF8StringEncoding];
        
        // append "/envelopes" URI to your baseUrl and use as endpoint for signature request call
        NSString *signatureRequestURL = [NSString stringWithFormat:@"%@/envelopes",baseUrl];
        
        // initialize a request object with the following url, method, and body
        NSMutableURLRequest *signatureRequest = [self initializeRequest:signatureRequestURL setMethod:@"POST" setBody:data];
        
        // add content-type and authorization headers
        [self addRequestHeaders:signatureRequest];
        
        // Send the signature request...
        [NSURLConnection sendAsynchronousRequest:signatureRequest queue:[NSOperationQueue mainQueue] completionHandler:^(NSURLResponse *envelopeResponse, NSData *envelopeData, NSError *envelopeError) {
            
            NSError *jsonError = nil;
            NSDictionary *responseDictionary = [NSJSONSerialization JSONObjectWithData:envelopeData options:kNilOptions error:&jsonError];
            NSLog(@"Signature request sent, envelope info is: \n%@\n", responseDictionary);
            
            // parse envelopeId from resposne as it will be used in next request
            NSString *envelopeId = responseDictionary[@"envelopeId"];
            
            ///////////////////////////////////////////////////////////////////////////////////////
            // STEP 3 - Get the Embedded Signing View (aka recipient view) of the envelope
            ///////////////////////////////////////////////////////////////////////////////////////
            
            // simply set the returnUrl in the request body (user is directed here after signing)
            NSDictionary *embeddedRequestData = @{@"returnUrl": @"http://www.docusign.com/devcenter",
                                                  @"authenticationMethod" : @"none",
                                                  @"email" : email,
                                                  @"userName" : name,
                                                  @"clientUserId" : clientUserId    // must match |clientUserId| set is step 2
                                                  };
            
            // convert request body into an NSData object
            NSData* data = [[self jsonStringFromObject:embeddedRequestData] dataUsingEncoding:NSUTF8StringEncoding];
            
            // append /envelopes/{envelopeId}/views/recipient to baseUrl and use in request
            NSString *embeddedURL = [NSString stringWithFormat:@"%@/envelopes/%@/views/recipient", baseUrl, envelopeId];
            
            // initialize a request object with the following url, method, and body (no body for login api call)
            NSMutableURLRequest *embeddedRequest = [self initializeRequest:embeddedURL setMethod:@"POST" setBody:data];
            
            // add content-type and authorization headers
            [self addRequestHeaders:embeddedRequest];
            
            //*** make an asynchronous web request
            [NSURLConnection sendAsynchronousRequest:embeddedRequest queue:[NSOperationQueue mainQueue] completionHandler:^(NSURLResponse *embeddedResponse, NSData *embeddedData, NSError *embeddedError) {
                
                if (embeddedError) {   // succesful POST returns status 201
                    NSLog(@"Error sending request %@. Got Response %@ Error is: %@", embeddedRequest, embeddedResponse, embeddedError);
                    return;
                }
                
                // we use NSJSONSerialization to parse the JSON formatted response
                NSError *jsonError = nil;
                NSDictionary *responseDictionary = [NSJSONSerialization JSONObjectWithData:embeddedData options:kNilOptions error:&jsonError];
                NSString *embeddedURLToken = responseDictionary[@"url"];
                
                //--- display results
                NSLog(@"URL token created - please navigate to the following URL to start the embedded signing workflow:\n\n%@\n\n", embeddedURLToken);
            }];
        }];
    }];
}

//***********************************************************************************************
// --- HELPER FUNCTIONS ---
//***********************************************************************************************
- (NSMutableURLRequest *) initializeRequest:(NSString *) url setMethod:(NSString *) method setBody:(NSData *) body
{
    // create a request using the passed parameters for url, method, and body
    NSMutableURLRequest *request = [[NSMutableURLRequest alloc] init];
    [request setHTTPMethod:method];
    [request setHTTPBody:body];
    [request setURL:[NSURL URLWithString:url]];
    return request;
}
/////////////////////////////////////////////////////////////////////////////////////////////////
- (void) addRequestHeaders:(NSMutableURLRequest *) request
{
    // set JSON formatted X-DocuSign-Authentication header (XML format also accepted)
    NSDictionary *authenticationHeader = @{ @"Username": email, @"Password" : password, @"IntegratorKey" : integratorKey };
    
    // add the auth header to the request object
    [request setValue:[self jsonStringFromObject:authenticationHeader] forHTTPHeaderField:@"X-DocuSign-Authentication"];
    
    // also set the Content-Type header (other accepted type is application/xml)
    [request setValue:@"application/json" forHTTPHeaderField:@"Content-Type"];
}
/////////////////////////////////////////////////////////////////////////////////////////////////
- (NSDictionary *) getHttpResponse:(NSMutableURLRequest *) request response:(NSURLResponse *) response data:(NSData *) data error:(NSError *) error
{
    if (error) {
        NSLog(@"Error sending request %@\n. Got Response %@\n Error is: %@\n", request, response, error);
        return nil;
    }
    // we use NSJSONSerialization to parse the JSON formatted response
    NSError *jsonError = nil;
    return [NSJSONSerialization JSONObjectWithData:data options:kNilOptions error:&jsonError];
}
/////////////////////////////////////////////////////////////////////////////////////////////////
- (NSString *)jsonStringFromObject:(id)object {
    NSString *string = [[NSString alloc] initWithData:[NSJSONSerialization dataWithJSONObject:object options:0 error:nil] encoding:NSUTF8StringEncoding];
    return string;
}