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. Added new API calls that include additional options for customization and support for Center Stage and deprecated previous calls in version 10.3.

    Related Articles

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