Documentation

Getting Started

We have taken care to make sure Snapper is easy to integrate with your website, to get started simply include this script tag in the <head> of your html document:

<html>
  <head>
    <script src="http://www.webcamsnapper.com/latest.js"></script>
  </head>
  ...

The Snapper script is small (only 8kb compressed) so won't slow down your page load times. All other assets are loaded on demand from a global content delivery network and cached for future use.

Once included on your site, you can add webcam inputs to your forms or control Snapper using the Javascript API

Server side integration is also a breeze, all you have to do is download the image from a temporary URL and store the photo on your server. See our examples of how to do this with PHP, Ruby, Python, .Net, and Coldfusion.

Don't forget Snapper is only free for non commercial and trial usage. If using the Snapper on a commercial website you should purchase a license. This helps fund future development and keeps us fed.

Enhancing Forms

To make integration with forms easy we have added support for a new input element <input type="webcam" />.
When the document loads webcam inputs are either rendered as a "Take Photo" button or optionally replaced with the Snapper widget.

<form action="/save_snap" method="POST">
  <input type="webcam" name="snap" />
  <input type="submit" />
</form>

This is how it works:

Clicking the "Take Photo" button opens the Snapper widget in an overlay window
The user takes a photo & clicks "Save", this closes the overlay window
A thumbnail of the photo is displayed along with a "Change Photo" button in the form
Upon form submission, the param "snap" is sent to the server containing a temporary URL
On the server you can download and the photo from the temporary URL and save it

Please note: We only provide temporary photo storage. You must download and save images to your server within 24 hours if you wish to keep them.

Optional Attributes

Input webcam elements support the usual HTML attributes such as 'value' and 'onchange'. You can also change the behavior and appearance by setting HTML5 "data-" attributes.

Attribute	Value	Usage
value	e.g. "http://server/current/photo.jpg"	Pass in an existing image URL
onchange	e.g. "alert(this.value);"	Execute code on value change
data-embed	"" (default) \| "onload" \| "onclick"	Embed in form rather than overlay
data-config	"{}" (default) \| {"size": "large", "output_format": "png"}	Pass JSON encoded instance config
data-take-label	"Take Photo"	Change button text
data-change-label	"Change Photo"	Change button text

Javascript API

For those who need more control we have a simple JavaScript API. There are 3 methods available on the global 'Snapper' object. Call 'configure' to set the global config, 'show' to load the Snapper in an overlay window, or 'embed' to embed the Snapper into your page.

Here is a quick example showing how to use the Snapper API with the JavaScript framework JQuery.

$(function(){
  
  // Set global config
  Snapper.configure({
    snapper_size: 'tiny', // set the default snapper size to tiny
    snapper_border: 'round shadow', // render snapper with a round corners and a shadow
    output_format: 'png' // switch from 'jpg' to use 'png' when saving.
    // see configuration section of docs for full list.
  });
  
  // Load snapper when a button is clicked
  $('#snap_button').click(function(){
    Snapper.show({ // open snapper in an overlay window
      complete: function(image){ // called when the photo has been saved
        // e.g. set value of hidden form element 
        $('#my_hidden_field').val(image);
      }, 
      // instance config 
      snapper_size: 'medium' // override the default size, set it to medium 
    });
  });
  
  // Embed snapper into the page
  Snapper.embed({ // renders snapper in the page
    target: 'my_photo_booth', // pass the ID of the div where you want snapper to embed
    complete: function(image){ // called when the photo has been saved
      // e.g. ajax call to save photo on server
      $.post('/my_save_handler', {snap: image}, function(){
        alert('Snap saved');
      });
    },
    // instance config
    output_format: 'jpg', // set output format to jpg
    jpg_quality: 90 // use high quality
  }); 
  
});

The example above uses the jQuery framework. We don't include jQuery with the Snapper so if you wish to use it with Snapper you should include it in your document. If you are using a different JavaScript framework you will need to adjust the code above to fit your framework.

Configuration Options

We have tried to pick sensible defaults for all configuration options, however we know that sometimes you need to tweak things. Here is a list of the config settings you can change along with an example setting the global config.

      
// Set global config
Snapper.configure({
  
  // For commercial use, set the domain and license key globally.
  license_domain: '...', 
  license_key: '...', 
  
  // Change the size
  snapper_size : 'small', 
  
  // tiny => 320x240
  // small => 400x300 
  // standard => 480x360 
  // medium => 560x420 
  // large => 640x480 
  // huge => 800x600

  // Change the border size
  snapper_border: 'round shadow', // ('square' or 'round', 'shadow' optional) 
  
  // Change flash security popup type
  camera_security_type: 'remember', // ('ask', 'remember')
  
  // Adjust output image format and size
  image_size: '640x480', // ('320x240', '480x360', '640x480', '800x600') 
  output_format: 'jpg', // ('jpg', 'png') 
  jpg_quality: 80, // (0-100)
    
  // Hide features you don't need
  hide_321_btn: true, 
  hide_effect_btn: true, 
  
  /* EXPERIMENTAL OPTIONS */
  
  // The standard method of saving uploads the image and returns a temporary URL.
  // It is possible to skip the upload and return the base64 data as a data url. 
  // For more info on data urls see: http://en.wikipedia.org/wiki/Data_URI_scheme
  save_method: 'base64' // ('upload', 'base64')
  
});

Server Integration

If using the hosted version of Snapper all you need to do on the server is download the image from the temporary URL then store it on your server. We have various examples showing how this is done in different programming languages.

PHP
Ruby
Python
Coldfusion
C#
Visual Basic
JavaScript

<?php 
// grab the temp url for the image
$temp_url = $_POST['snap'];
$save_as = "snaps/" . basename($temp_url);

// create snaps folder if needed
if(!is_dir('snaps')){ mkdir('snaps'); }

// download the image data using curl
$ch = curl_init();
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); 
curl_setopt($ch, CURLOPT_URL, $temp_url);
$image_data = curl_exec($ch);
curl_close($ch);

// save the image to disk
file_put_contents($save_as, $image_data);

// check
exec('open '.$save_as);
?>

require 'open-uri'

# grab the temp url for the image
temp_url = params['snap']
save_as = "snaps/#{temp_url.split("/")[-1]}"

# create snaps folder if needed
Dir.mkdir("snaps") if not File.exists?("snaps")

# download the image data
open(temp_url) do |data| 
  # save the image to disk
  open(save_as, 'w') do |f|
    f.puts(data.read)
  end
end

# check
`open #{Dir['./snaps/*'][0]}`

import os, urllib2

# grab the temp url for the image
temp_url = request.post.get('snap')
save_as = os.path.join('snaps', os.path.basename(temp_url))

# create snaps folder if needed
if not os.path.isdir(os.path.dirname(save_as)):
    os.path.mkdir(os.path.dirname(save_as))

# download the image data
image_data = urllib2.urlopen(temp_url).read()

# save the image to disk
f = open(save_as,'w+') 
f.write(image_data)
f.close()

# check
os.system('open %s' % save_as)

<!--- grab the temp url for the image --->
<cfset tempUrl="#FORM.snap#">
<cfset saveFile=getFileFromPath(tempUrl)>
<cfset saveDir=ExpandPath("snaps")>

<!--- create snaps folder if needed --->
<cfif NOT DirectoryExists( saveDir )>
 <cfdirectory directory="#saveDir#" action="create"> 
</cfif>

<!--- download the image data and save the image to disk --->
<cfhttp url="#tempUrl#" getAsBinary="Yes" path="#saveDir#" file="#saveFile#" />

WebClient client = new WebClient();
string tempURL = Request.Form['snap']
string saveDir = Server.MapPath('snaps');
string saveAs = saveDir + '/' + Path.GetFileName(tempURL)
if(!File.Exists(saveDir)){
  System.IO.Directory.Create(saveDir)
}
client.DownloadFile(tempURL, saveAs)

Dim client As New WebClient
Dim tempURL As String = Request.Form['snap']
Dim saveDir As String = Server.MapPath("snaps");
Dim saveAs As String = saveDir + "/" + Path.GetFileName(tempURL)
If Not File.Exists(saveDir) Then
  System.IO.Directory.Create(saveDir)
End
client.DownloadFile(tempURL, saveAs)

// node.js example 

var http = require('http');
var sys = require('sys');
var fs = require('fs');
var url = require('url');
var http = require('http');
var path = require('path');

var server = http.createServer(function(req, res) {
  
  switch (url.parse(req.url).pathname) {
    case '/':
      res.writeHead(200, {'Content-Type': 'text/html'});
      res.write(
        '<script src="http://www.webcamsnapper.com/latest.js" />'+
        '<form action="/save_snap" method="get">'+
        '<input type="webcam" name="snap">'+
        '<input type="submit" value="Submit">'+
        '</form>'
      );
      res.end();
      break;
    case '/save_snap':
      var params = url.parse(req.url, true).query;
      var tempURL = url.parse(params['snap']);
      var client = http.createClient(80, tempURL.hostname);
      var saveAs = 'snaps/'+path.basename(tempURL.pathname);
      var file = fs.createWriteStream(saveAs);
      var request = client.request('GET', tempURL.pathname, {'host': tempURL.hostname});
      request.addListener('response', function (response) {
        response.addListener('data', function(chunk){file.write(chunk);});
        response.addListener('end', function(){file.end();});
      })
      request.end();
      res.writeHead(200, {'Content-Type': 'text/plain'});
      res.write('Downloaded: '+params['snap']+'\n');
      res.write('Saved as: '+saveAs+'\n');
      res.end();
      break;
    default:
      res.writeHead(404, {'Content-Type': 'text/plain'});
      res.write('404\n');
      res.end();
      break;
  }
});
server.listen(8000);

The Pro version of Snapper handles image uploads directly on your site.
Sample code is included with the Snapper files after purchase.

Webcam Snapper