Capture API: Photo & Video

Using custom JavaScript functions, you can access the camera and save the result locally on the iPad in Kiosk Pro's Documents folder. When using these calls, the standard iOS camera interface is shown on screen and the kiosk visitor triggers the capture by touching the screen. Before saving the picture or video, the visitor can review and accept the picture or video or choose to try again or cancel.

Several functions include countdowns and/or timers to determine video length. For example, it's possible to set an automatic countdown for photo capture where the camera image is shown on screen, overlaid by the countdown of the number of seconds until the image will be snapped, which then happens automatically without direct visitor interaction. The resulting image is shown overlaid with the alert message defined until the alert is dismissed or the idle timer triggers.

By default, the app always returns images in maximum quality of the device. If your use case requires smaller image files (to maximize storage on the device, for example), we've added calls to allow you to resize images to a certain width and height (expressed in pixels) prior to saving.

A custom function can also be used to determine whether to default to the front or back camera.

Resulting image and video files can be accessed directly on the device by a locally stored HTML page, manually synced off the device, or retrieved remotely through Dropbox sync to a unique content folder.

Functions

Requirements

  • Access JavaScript API
    • By Import - recommended, works both online & offline, requires inclusion of kiosk_functions.js prior to any of the following calls.
    • By Injection - only works offline, may not be available 'onload'.

Sample Code

This sample code relies on the JavaScript APIs built into Kiosk Pro and will not run successfully in other browsers or within our in-app help interface.  

To run sample code, set the app's homepage to http://www.kioskproapp.com/snap

Download Sample Code


takePhotoToFile

This function triggers the native iOS camera interface to capture a photo. Using this function, the visitor must trigger photo capture through the standard iOS camera interface and is given the opportunity to 'Retake' or to cancel out of the camera. Once they take a picture and tap 'Use Photo', the photo is saved.

Format
takePhotoToFile(filename,callback);
		
Parameters
  • filename = [required, string] name of the image file to be saved to the device. As photos are always saved in .png format, this file extension is automatically added to any filename defined through this parameter.
  • callback = [string] name of callback function which will be called with the following signature: callback(success).
Callback format
callback(success);
		
Callback return values success = if defined, the function successfully captured and saved an image to the Kiosk Pro document's folder.


kp_PhotoVideo_takePhotoToFileResize

Added in 9.2

This function triggers the native iOS camera interface to capture a photo. Using this function, the visitor must trigger photo capture through the standard iOS camera interface and is given the opportunity to 'Retake' or to cancel out of the camera. Once they take a picture and tap 'Use Photo', the photo is resized to the width and height defined in the call and saved to the app's Documents folder.

Please note that if the height and width defined do not match the aspect ratio of the original image, then the image will be resized and then cropped as necessary to meet the height and width defined.

Format
kp_PhotoVideo_takePhotoToFileResize(filename, callback, width, height);
		
Parameters
  • filename = [required, string] name of the image file to be saved to the device. As photos are always saved in .png format, this file extension is automatically added to any filename defined through this parameter.
  • callback = [string] name of callback function which will be called with the following signature: callback(success).
  • width = [string] width of saved image in pixels.
  • height = [string] height of saved image in pixels.
Callback format
callback(success);
		
Callback return values success = if defined, the function successfully captured and saved an image to the Kiosk Pro document's folder.


takePhotoWithCountdownToFile

This function triggers an automatic photo capture using an on-screen countdown. The countdown is defined in the parameters of the call, along with the message shown after a successful capture and the number of seconds to display the photo taken after the message is dismissed.  

Format
takePhotoWithCountdownToFile(filename, callback, countdownTimer, alertMessageOnSuccess, secondsToShowImage);
		
Parameters
  • filename = [required, string] name of the image file to be saved to the device. As photos are always saved in .png format, this file extension is automatically added to any filename defined through this parameter.
  • callback = [string] name of callback function which will be called with the following signature: callback(success).
  • countdownTimer =  [integer] number of seconds to count down prior to capture.
  • alertMessageOnSuccess = [string] alert message displayed after a successful capture.
  • secondsToShowImage = [integer] number of seconds to display image on screen following capture.
Callback format
callback(success);
		
Callback return values success = if defined, the function successfully captured and saved an image to the Kiosk Pro document's folder.


kp_PhotoVideo_takePhotoWithCountdownToFileResize

Added in 9.2

This function triggers an automatic photo capture using an on-screen countdown. The countdown is defined in the parameters of the call, along with the message shown after a successful capture and the number of seconds to display the photo taken after the message is dismissed. Once complete, the photo is resized to the width and height defined in the call and saved to the app's Documents folder.

Please note that if the height and width defined do not match the aspect ratio of the original image, then the image will be resized and then cropped as necessary to meet the height and width defined.

Format
kp_PhotoVideo_takePhotoWithCountdownToFileResize(filename, callback, countdownTimer, alertMessageOnSuccess, secondsToShowImage, width, height);
		
Parameters
  • filename = [required, string] name of the image file to be saved to the device. As photos are always saved in .png format, this file extension is automatically added to any filename defined through this parameter.
  • callback = [string] name of callback function which will be called with the following signature: callback(success).
  • countdownTimer =  [integer] number of seconds to count down prior to capture.
  • alertMessageOnSuccess = [string] alert message displayed after a successful capture.
  • secondsToShowImage = [integer] number of seconds to display image on screen following capture.
  • width = [string] width of saved image in pixels.
  • height = [string] height of saved image in pixels.
Callback format
callback(success);
		
Callback return values success = if defined, the function successfully captured and saved an image to the Kiosk Pro document's folder.


takeVideoToFile

This function captures video using the native iOS camera interface. Using this function, the visitor must start and end video capture through the standard record button and is given the opportunity to watch and 'Retake' or to cancel out of the camera. Once they tap 'Use Video', the video is saved to the specified location.

Format
takeVideoToFile(filename,callback);
		
Parameters
  • filename = [required, string] name of the video file to be saved to the device. Video is saved using the H.264 codec and can be saved as .mov (default if not specified as a part of the filename defined through this parameter) or .mp4.
  • callback = [string] name of callback function which will be called with the following signature: callback(success).
Callback format
callback(success);
		
Callback return values success = if defined, the function successfully captured and saved a video to the Kiosk Pro document's folder.


takeVideoWithCountdownToFile

This allows you to take a video of a predetermined length with an on-screen countdown prior to start and then another showing how long until the recording ends. This works well in situations where storage on the device is limited or the resulting video needs to be limited to a specific duration. 

Format
takeVideoWithCountdownToFile(filename, callback, countdownTimer, recordingTimer, showRecordingTimer, alertMessageOnSuccess);
		
Parameters
  • filename = [required, string] name of the video file to be saved to the device. Video is saved using the H.264 codec and can be saved as .mov (default if not specified as a part of the filename defined through this parameter) or .mp4.
  • callback = [string] name of callback function which will be called with the following signature: callback(success).
  • countdownTimer = [integer] number of seconds to count down prior to recording.
  • recordingTimer = [integer] number of seconds to record video.
  • showRecordingTimer = [boolean] defines whether to display the countdown timer on screen during recording:
    • 1 = show the timer.
    • 0 = hide the timer.
  • alertMessageOnSuccess = [string] alert message displayed after a successful capture.

Callback format
callback(success);
		
Callback return values success = if defined, the function successfully captured and saved a video to the Kiosk Pro document's folder.


takeVideoWithEndingByTouchingScreen

This function allows video capture with an on-screen countdown prior to start. Once the recording starts, you can display a message on-screen and/or a timer showing the visitor how long the recording has been running. Recording can be ended through a pre-defined timer or through a visitor tap to the screen.  

Format
kp_PhotoVideo_takeVideoWithEndingByTouchingScreen(filename, callback, countdownTimer, recordingTimer, recordingMessage, showRecordingTimer, alertMessageOnSucces);
		
Parameters
  • filename = [required, string] name of the video file to be saved to the device, expressed as a string. Video is saved using the H.264 codec and can be saved as .mov (default if not specified as a part of the filename defined through this parameter) or .mp4.
  • callback = [string] name of callback function which will be called with the following signature: callback(success).
  • countdownTimer = [integer] number of seconds to count down prior to recording.
  • recordingTimer = [integer] number of seconds to record video.
  • recordingMessage = [string] text to display on-screen during recording.
  • showRecordingTimer = [boolean] defines whether to display the countdown timer on screen during recording:
    • 1 = show the timer.
    • 0 = hide the timer.
  • alertMessageOnSuccess = [string] alert message displayed after a successful capture.
Callback format
callback(success);
		
Callback return values success = if defined, the function successfully captured and saved an image to the Kiosk Pro document's folder.


kp_PhotoVideo_setCameraType

This function sets which camera (front or back) should be used when a photo or video capture is called. Note: The app defaults to the front camera unless otherwise instructed.

Format
kp_PhotoVideo_setCameraType(cameraLocation,callback)
		
Parameters
  • cameraLocation = [integer] sets which camera the device should use. Possible values are:
    • 0 = rear camera
    • 1 = front camera
  • callback = [string] name of callback function which will be called with the following signature: callback(success).
Callback format
callback(success);
		
Callback return values success = if defined, the function successfully set the camera location.


kp_PhotoVideo_getCameraType

This function triggers a callback showing which camera (front or back) will currently be shown when the camera is opened for photo or video capture.

Format
kp_PhotoVideo_getCameraType(callback)
		
Parameters callback = [string] name of callback function which will be called with the following signature: callback(cameraLocation).
Callback format
callback(cameraLocation);
		
Callback return values cameraLocation = [integer] returns which camera the device is currently set to use. Possible values are:
  • 0 = rear camera
  • 1 = front camera

Still stuck? How can we help? How can we help?