Getting Started with Dropbox Sign Embedded Signing with Ruby on Rails

Scritto da
Freddy Rangel
4
minute read
RSS icon

Dropbox Sign provides the most robust and
Instead of asking your users to leave your website to sign a document, you can have them do it easily right in your app.

It's pretty easy to get started with just a few lines of code.



Let's walk through a simple example of embedding a document for signing on your application.


This example is assuming your app is a Rails app, but if you're using another framework like Sinatra it works roughly the same way.

First, if you haven't already done so,

, but to get things moving along we just need a few lines of code. 

Let’s first set up a route to our new callback endpoint: 

# config/routes.rb Rails.application.routes.draw do
 post '/signatures/callbacks',
   to: 'signatures#callbacks'
end 

Now let's add the endpoint controller action itself. Dropbox Sign requires the endpoint to always respond with status 200 and with 'Hello API Event Received' in the response body, regardless of whether the callback has been handled correctly. 

# app/controllers/signatures_controller.rb

class SignaturesController < ApplicationController
 skip_before_action :verify_authenticity_token, only: [:callbacks]

 def callbacks
   render json: 'Hello API Event Received', status: 200
 end
end 

We’ll want to test this endpoint to make sure it's set up correctly. Sadly, since our endpoint is only accessible from our local machine, we need some help exposing this endpoint to the world. 

. It's a free and easy to use tunneling service that works great for exposing your local server to the internet. If you're on a Mac it's really easy to install with Homebrew:
brew install ngrok 

Now let's expose the server. 

Let's fire up the server first: rails s 

And in a separate tab, let's fire up ngrok:
ngrok 3000 

Here we're telling ngrok to watch port and tunnel port 3000, which is where our rails server is listening on. Notice that when you run ngrok it will give you a forwarding url which is where the outside world can reach your local server.

ngrok might change this url randomly in the future so I recommend setting up a custom subdomain. In order to do that you'll need an ngrok account but you can easily sign up with your github account here:

Then you can run the following: 

ngrok -authtoken=coolAuthTokenDude -subdomain=mycoolapp 3000 

Now let's take our cool new ngrok url and use that for our callback url that our Dropbox Sign API app can use. Make sure to click the “TEST” button to make sure everything is set up correctly.

Once you create the application, make sure to retrieve the app's client id. We're going to use it shortly.

Now that we’ve created our Dropbox Sign app, we can get ready to make an embedded signature request. Unless doing raw HTTP calls to an API happens to be your thing (or whatever kids are doing these days), I suggest reaching for the handy HelloSign Ruby SDK. 

Let's add it to the Gemfile: 

gem 'hellosign-ruby-sdk' 

And let's not forget to run:
bundle install 

Alright, now we need to do some configuration using your API key and test app client id. If you're working on a Rails app, you can easily do this with an initializer. 

# config/initializers/hello_sign.rb

require 'hello_sign'
HelloSign.configure do |config|
 # 

You might want to put all these keys in environment variables or you can YOLO it. 

config.api_key = 'api_key'
 config.client_id = 'client_id'
end 

Now let's create our first embedded signature request. The implementation details are going to be different from app to app, but here we're going to go with something simple and set up a form where we submit a signer's name and email. 

Then, we're going to immediately open up that document inside the app. 

Let's start with updating our routes: 

# config/routes.rb

Rails.application.routes.draw do
 resources :signatures, only: [:new, :create] do
   collection do
     post 'callbacks'
   end
 end
end 

Next we're going to create the form. Let's add the new embedded request form controller action:
# app/controllers/signatures_controller.rb

def new
end 

Now we need the view: 

# app/views/signatures/new.html.erb

<%= form_tag signatures_path, method: :post do %>
 <%= label_tag 'Name' %>
 <%= text_field_tag :name %>
 <%= label_tag 'Email' %>
 <%= text_field_tag :email %>
 <%= submit_tag 'Create Embedded Signature Request' %>
<% end %> 

Now let's add the create action: 

# app/controllers/signatures_controller.rb

def create
 embedded_request = create_embedded_request(name: params[:name], email: params[:email])
 @sign_url = get_sign_url(embedded_request)
 render :embedded_signature
end

private

def create_embedded_request(opts = {})
 HelloSign.create_embedded_signature_request(
   test_mode: 1, #Set this to 1 for 'true'. 'false' is 0
   client_id: 'your_client_id',
   subject: 'My first embedded signature request',
   message: 'Awesome, right?',
   signers: [
     {
       email_address: opts[:email],
       name: opts[:name]
     }
   ],
   files: ['offer_letter.pdf']
 )
end

def get_sign_url(embedded_request)
 sign_id = get_first_signature_id(embedded_request)
 HelloSign.get_embedded_sign_url(signature_id: sign_id).sign_url
end

def get_first_signature_id(embedded_request)
 embedded_request.signatures[0].signature_id
end 

Here we're doing two things:

  1. We are sending an embedded signature request to Dropbox Sign.
  2. Once we have created a request, we are grabbing the “signature_id” for the first signer and using that to retrieve the sign_url, which we're going to use in the view.


Speaking of which, here it is:






In the view, we’re pulling a script from a CDN that will help us embed our document in our app. This gives us a Dropbox Sign object in the browser which we will initialize and open our document with the sign_url we passed in from the controller. 

.


Logo di condivisione social FacebookLogo di condivisione social TwitterLogo di condivisione social LinkedInRSS icon
Up next: