API: Capture Photos & Videos

Access the camera and save the result locally on the iPad in Kiosk Pro's documents folder. 

Resulting files can be accessed directly on the device by a locally stored HTML page, manually transferred to a computer, retrieved remotely through Dropbox Sync, or in the case of image files, returned as a Base64 string using this API. Files can also be managed using the Manage Local Files API.

In this article

Requirements

Kiosk Pro Plus and Enterprise

  • Integration of our JavaScript API into your webpage
    • Sample code to run within the app and download for integration into your own project is available here.
    • Best practices for working with the JavaScript API are available here.
  • App Settings
    • Content > JavaScript API > Access JavaScript API = By Import
  • iOS/iPadOS Permissions
    • Camera - more on enabling specific iOS/iPadOS permissions here
  • Storage of resulting files in Kiosk Pro's Documents folder
    • Due to sandboxing in iOS/iPadOS, Kiosk Pro is unable to store local files outside of its own Documents folder. 

Triggers via API Functions

General Functions

Photo Functions

Video Functions

Check Current Default Camera

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

Format 
kp_PhotoVideo_getCameraType(callback)
Parameters callback - [string] the name of the callback to be triggered after the function has been executed
Callback format 
callback(cameraLocation);
Callback return values cameraLocation - [number] returns which camera the device is currently set to use. Possible values are:
  • 0 - rear camera
  • 1 - front camera

Set Front or Rear Camera as Default

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] the name of the callback to be triggered after the function has been executed
Callback format 
callback(success);
Callback return values success - if defined, the function successfully set the camera location

Check Current Flash Mode

This function triggers a callback returning the flash mode which will be set when the camera is opened for photo or video capture. In instances where the device does not have a flash for the camera currently in use, this will be ignored.

Format 
kp_PhotoVideo_getFlashMode(callback)
Parameters callback - [string] the name of the callback to be triggered after the function has been executed
Callback format 
callback(flashMode);
Callback return values flashMode - [integer] representing the current flash mode configured. Possible values are:
  • -1 - off
  • 0 - auto
  • 1 - on

Set Flash Mode

This function sets how flash mode should be configured when the camera is opened for photo or video capture. In instances where the device does not have a flash for the camera currently in use, this will be ignored.

Format 
kp_PhotoVideo_setFlashMode(flashMode, callback)
Parameters
  • flashMode - [integer] representing the flash mode to be set. Possible values are:
    • -1 - off
    • 0 - auto
    • 1 - on
  • callback - [string] the name of the callback to be triggered after the function has been executed
Callback format 
callback(success);
Callback return values success - if defined, the function successfully set the flash mode requested

Capture Full Resolution Photo

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.

This function uses the native iOS interface to allow the visitor to trigger and review the photo, which also includes buttons to trigger the flash mode used and switch between the front and rear camera. While these options can be preconfigured using the API calls above, they can be changed by the visitor prior to capturing the image. To prevent this, you may choose to use the calls below featuring a countdown to trigger the camera which do not allow access to these options.

Format 
takePhotoToFile(filename, callback);
Parameters
  • filename - [required, string] the 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] the name of the callback to be triggered after the function has been executed
Callback Format 
callback(success, error);
Callback Return Values
  • success - if defined, a photo was successfully captured and saved to the Kiosk Pro document's folder
  • error - [object] the error returned when printing fails. Includes the following:
    • domain - [string] where the error occurred
    • code - [integer] the error code
    • description - [string] a description of the error
    • debugDescription - [string] a detailed description of the error

Capture Photo with Specific Dimensions

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.

This function uses the native iOS interface to allow the visitor to trigger and review the photo, which also includes buttons to trigger the flash mode used and switch between the front and rear camera. While these options can be preconfigured using the API calls above, they can be changed by the visitor prior to capturing the image. To prevent this, you may choose to use the calls below featuring a countdown to trigger the camera which do not allow access to these options.

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] the 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] the name of the callback to be triggered after the function has been executed
  • width - [string] the width of saved image in pixels
  • height - [string] the height of saved image in pixels
Callback format 
callback(success, error);
Callback return values
  • success - if defined, a photo was successfully captured and saved to the Kiosk Pro document's folder
  • error - [object] the error returned when printing fails. Includes the following:
    • domain - [string] where the error occurred
    • code - [integer] the error code
    • description - [string] a description of the error
    • debugDescription - [string] a detailed description of the error

Capture Full Resolution Photo with Countdown

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] the 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] the name of the callback to be triggered after the function has been executed
  • countdownTimer - [integer] the number of seconds to count down prior to capture
  • alertMessageOnSuccess - [string] the alert message displayed after a successful capture. If empty (''), no alert will be shown
  • secondsToShowImage - [integer] the number of seconds to display image on screen following capture
Callback format 
callback(success, error);
Callback return values
  • success - if defined, a photo was successfully captured and saved to the Kiosk Pro document's folder
  • error - [object] the error returned when printing fails. Includes the following:
    • domain - [string] where the error occurred
    • code - [integer] the error code
    • description - [string] a description of the error
    • debugDescription - [string] a detailed description of the error

Capture Photo with Specific Dimensions & Countdown

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] the 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] the name of the callback to be triggered after the function has been executed
  • countdownTimer - [integer] the number of seconds to count down prior to capture
  • alertMessageOnSuccess - [string] the alert message displayed after a successful capture
  • secondsToShowImage - [integer] the number of seconds to display image on screen following capture
  • width - [string] the width of saved image in pixels
  • height - [string] the height of saved image in pixels
Callback format 
callback(success, error);
Callback return values
  • success - if defined, a photo was successfully captured and saved to the Kiosk Pro document's folder
  • error - [object] the error returned when printing fails. Includes the following:
    • domain - [string] where the error occurred
    • code - [integer] the error code
    • description - [string] a description of the error
    • debugDescription - [string] a detailed description of the error

Return Base64 String from Image File

This function translates an image file stored in Kiosk Pro's Documents folder into a Base64 string.

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 cropped as necessary to meet the height and width defined.

Format 
kp_PhotoVideo_base64FromScaledPhoto(fileName, width, height, callback);
Parameters
  • filename - [required, string] the full name of the image file to be returned as a Base64 string. If a filepath is required, it should be relative to the Kiosk Pro Document folder root
  • width - [string] the width of resized image in pixels
  • height - [string] the height of resized image in pixels
  • callback - [string] the name of the callback to be triggered after the function has been executed
Callback format 
callback(base64String, error);
Callback return values
  • base64String - the base64 string of the resized image
  • error - if defined, an array returning the reason for failure. Specific keys for this array are shown in the sample code.

Capture Video

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.

This function uses the native iOS interface to allow the visitor to trigger and review the video, which also includes buttons to trigger the flash mode used and switch between the front and rear camera. While these options can be preconfigured using the API calls above, they can be changed by the visitor prior to capturing the video. To prevent this, you may choose to use the calls below featuring a countdown to trigger the camera which do not allow access to these options.

Format 
	takeVideoToFile(filename,callback);
Parameters
  • filename - [required, string] the 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] the name of the callback to be triggered after the function has been executed
Callback format 
callback(success, error);
Callback return values
  • success - if defined, a video was successfully captured and saved to the Kiosk Pro document's folder
  • error - [object] the error returned when printing fails. Includes the following:
    • domain - [string] where the error occurred
    • code - [integer] the error code
    • description - [string] a description of the error
    • debugDescription - [string] a detailed description of the error

Capture Video with Countdown

This allows you to take a video of a predetermined length with an on-screen countdown prior to start and then another optional countdown 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 
kp_PhotoVideo_takeVideoWithCountdown(filename, callback, countdownTimer, recordingTimer, showRecordingTimer, alertMessageOnSuccess);
Parameters
  • filename - [required, string] the 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] the name of the callback to be triggered after the function has been executed
  • countdownTimer - [integer] the number of seconds to count down prior to recording
  • recordingTimer - [integer] the number of seconds to record video
  • showRecordingTimer - [boolean integer] defines whether to display the countdown timer on screen during recording:
    • 1 - show the timer
    • 0 - hide the timer

  • alertMessageOnSuccess - [string] the alert message displayed after a successful capture.

Callback format 
callback(success, error);
Callback return values
  • success - if defined, a video was successfully captured and saved to the Kiosk Pro document's folder
  • error - [object] the error returned when printing fails. Includes the following:
    • domain - [string] where the error occurred
    • code - [integer] the error code
    • description - [string] a description of the error
    • debugDescription - [string] a detailed description of the error

Capture Video & Tap Screen to End Recording

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] the 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] the name of the callback to be triggered after the function has been executed
  • countdownTimer - [integer] the number of seconds to count down prior to recording
  • recordingTimer - [integer] the number of seconds to record video
  • recordingMessage - [string] the text to display on-screen during recording
  • showRecordingTimer - [boolean integer] defines whether to display the countdown timer on screen during recording:
    • 1 - show the timer
    • 0 - hide the timer
  • alertMessageOnSuccess - [string] the alert message displayed after a successful capture
Callback format 
callback(success, error);
Callback return values
  • success - if defined, a video was successfully captured and saved to the Kiosk Pro document's folder
  • error - [object] the error returned when printing fails. Includes the following:
    • domain - [string] where the error occurred
    • code - [integer] the error code
    • description - [string] a description of the error
    • debugDescription - [string] a detailed description of the error

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 kioskgroup.com/photo-video-api
  • To download a .zip of sample code, click here.

Change Log

  • Added in version 1.3. Ability to check and set specific camera used added in version 3.4. Ability to capture photos with specific dimensions added in version 9.2. Ability to return Base64 string added in version 9.4. Ability to set the flash mode added in version 10.0

Related Articles

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