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.
Requirements
- 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 & Microphone - 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
Start Photo or Video Capture
This function triggers the camera interface based on a set configuration, such as which camera to use, whether to use flash, etc.
Format | kp_PhotoVideo_startNewCaptureFlow(taskJSON, parsingJSONReportCallback, workingReportCallback) |
Parameters |
|
Callback format for "parsingJSONReportCallback" | parsingJSONReportCallback(report); |
Callback return values |
|
Callback format for "workingReportCallback" | function workingReportCallback(succeded, error); |
Callback return values |
|
Cancel Capture
This function cancels the current photo or video capture.
Format | kp_PhotoVideo_cancelCaptureFlow(callback); |
Parameters |
|
Callback Format | callback(canceled); |
Callback Return Values |
|
Check if Capture is in Progress
This function checks to see if a photo or video capture is in progress.
Format | kp_PhotoVideo_isCaptureFlowInProgress(callback); |
Parameters |
|
Callback Format | callback(inProgress); |
Callback Return Values |
|
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 |
|
Callback format | callback(base64String, error); |
Callback return values |
|
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. Updated and added support for Center Stage in version 10.3.
Related Articles
Deprecated in 10.3
The following is documented as a reference for content existing prior to 10.3. New users should reference the new functions above.
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
- Integration of our JavaScript API into your webpage
- 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
- Check Current Default Camera
- Set Front or Rear Camera as Default
- Check Current Flash Mode
- Set Flash Mode
Photo Functions
- Capture Full Resolution Photo
- Capture Photo with Specific Dimensions
- Capture Full Resolution Photo with Countdown
- Capture Photo with Specific Dimensions & Countdown
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:
|
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 |
|
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:
|
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 |
|
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 |
|
Callback Format | callback(success, error); |
Callback Return Values |
|
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 |
|
Callback format | callback(success, error); |
Callback return values |
|
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 |
|
Callback format | callback(success, error); |
Callback return values |
|
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 |
|
Callback format | callback(success, error); |
Callback return values |
|
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 |
|
Callback format | callback(success, error); |
Callback return values |
|
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 |
|
Callback format | callback(success, error); |
Callback return values |
|
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 |
|
Callback format | callback(success, error); |
Callback return values |
|