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 & 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
  • taskJSON - [JSON Object] a configuration determining how a photo or video is captured. Keys include:
    • captureSession - [JSON object] a configuration determining details of the camera. Keys include:
      • captureMode - defines whether the capture is for photos or videos. Options include:
        • photo - opens the photo camera interface
        • video - opens the video camera interface
      • cameras - [JSON object] a configuration determining details of the camera. Keys include:
        • cameraPosition - defines which camera to use for capture. Options include:
          • front - uses the device's front camera
          • back - uses the device's back camera
        • zoomFactor - [JSON object] defines what level of zoom to use, and what to do if the zoom value is not available. Keys include:
          • val - [integer] defines what level of zoom to use for the capture
          • failureReaction - defines what to do if zoom value is not available. Options include:
            • stopFlow - the camera interface will be closed
            • fallbackToDefaults - zoom will be set to the default for the camera choice
        • flashMode - [JSON object] defines whether to use flash, and what to do if flash is not available. Keys include:
          • val - defines whether flash should be used. Options include:
            • on - flash is on
            • off - flash is off
            • auto - flash will be determined by the camera choice
          • failureReaction - defines what to do if flash is not available. Options include:
            • stopFlow - the camera interface will be closed
            • fallbackToDefaults - flash will be set to the default for the camera choice
          • showIcon - [integer] defines whether to show the flash icon during capture. Options include:
            • 1 - flash icon will be shown
            • 0 - flash icon will be hidden
        • centerStageMode - [JSON object] defines whether to use Center Stage and what to do if Center Stage is not available. Keys include:
          • val - defines whether Center Stage should be used. Options include:
            • on - Center Stage is on
            • off - Center Stage is off
            • auto - Center Stage will be determined by the camera choice
          • failureReaction - defines what to do if Center Stage is not available. Options include:
            • stopFlow - the camera interface will be closed
            • fallbackToDefaults - Center Stage will be set to the default for the camera choice
          • showIcon - [integer] defines whether to show the Center Stage icon during capture. Options include:
            • 1 - Center Stage icon will be shown
            • 0 - Center Stage icon will be hidden
    • autoFlow - [JSON object] Keys include:
      • beforeCapture -
        • prompt - [string] a
        • duration - [integer] a
        • showCounter - [integer] a
          • 1 - true
          • 0 - false
        • counterColor - [string] RGB code
      • duringCapture -[JSON object] Keys include:
        • canInterruptByTouching - [integer]
          • 1 - true
          • 0 - false
      • afterCapture - [JSON object] Keys include:
        • delay
          • - [integer] defines how long the result capture should display on-screen before it's dismissed
        • successMessage - [string] The messages shown when capture is successful
    • result - [JSON object] defines the name and location of the resulting file, as well as the size when capturing photos. Keys include:
      • filepath [string] definies the name and path of the resulting file saved. For example, "folder/video.mp4".
      • photoSize defines the size of the resulting photo. Options include:
        • w - the width of the photo
        • h - the height of the photo
Callback format for "parsingJSONReportCallback" 
parsingJSONReportCallback(report);
Callback return values
  • report - [array] defines the JSON configuration used with details about specific keys. Options include:
    • AbsentMandatoryKeys - lists required JSON keys that are not set
    • UnknownIgnoredKeys - lists JSON keys that are not recognized
    • KnownKeysWithIcorrectValues - lists JSON keys that have an invalid value
    • KnownIgnoredKeys - lists JSON keys that are not being applied
    • AbsentOptionalKeys - lists optional JSON keys that are not set
Callback format for "workingReportCallback" 
function workingReportCallback(succeded, error);
Callback return values
  • succeded - defines if a photo/video was successfully captured and saved to the Kiosk Pro document's folder. Options include:
    • 0 - [integer] not successful
    • 1 - [integer] successful
  • 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

Cancel Capture

This function cancels the current photo or video capture.

Format 
kp_PhotoVideo_cancelCaptureFlow(callback);
Parameters
  • callback - [string] the name of the callback to be triggered after the function has been executed
Callback Format 
callback(canceled);
Callback Return Values
  • canceled - [integer] defines if the capture is cancelled successfully. Options include:
    • 0 - capture was not cancelled
    • 1 - capture cancelled successfully

    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 - [string] the name of the callback to be triggered after the function has been executed
    Callback Format 
    callback(inProgress);
    Callback Return Values
  • inProgress - [integer] defines if the capture is in progress. Options include:
    • 0 - capture is not in progress
    • 1 - capture is in progress

    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.

    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

    Kiosk Pro Plus and Enterprise

    • 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

    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

    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

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