Status URL

 Top  Previous  Next

The status URL provides a way of sending status information about the app's status to a web site and for the web site to send commands back to the iPad. It can be used as a webhook to send information to your website or to online tools such as Integromat or Zapier.

 

When enabled the app will send an HTTPS POST request containing information about the app to the status URL at regular intervals. The web site receiving the HTTPS POST request can send a JSON response containing commands for the iPad to execute such as login details or sync information.

 

The status URL can be enabled in the App Settings screen by setting the URL to call, the update interval and an optional password.

 

Status Information Sent by the iPad

 

Below is an example of the status information sent by the app:

 

auth: "cc1c52665267d4972d0cc30fedeeb5eb8ed68d06"

hash: "2a47d388355b9f26412d89d1c996880e68f99f60"

time: "1589893063"

request: "ipad status"

username: "demo_ipad"

name: "Demo iPad"

model: "iPad Pro 11"" 

user_id: "d8cc7d4d-a2a8-4466-acc0-64ddf74df9bb",

"id": "95DFB8B0-2C03-4798-8473-236770988454"

status: "Startup"

info:

{

       "version":"1.1.2",

       "timeZoneOffset":3600,

       "battery\":100,

       "dropboxAccount":"",

       "signedInAs":"demo_acc",

       "time":1589893063,

       "totalInMB":122060,

       "model":"iPad8,9",

       "status":"Startup",

       "eventSyncServer":"https://bb4ipad.com/sync",

       "date":"20200804",

       "availableInMB":98418,

       "queues":{

               "dropboxQueue":0,

               "textQueue":0,

               "hubQueue":0,

               "uploadQueue":0,

               "emailQueue":0

       },

       "total": {

               "emailErrors":0,

               "photoTexts":45,

               "gifTexts":142,

               "gifEmails":283,

               "textErrors":0,

               "gifSessions":734,

               "photoSessions":350,

               "photosTaken":700,

               "photoEmails":384

       },

       "today":{

               "emailErrors":0,

               "photoTexts":21,

               "gifTexts":34,

               "gifEmails":56,

               "textErrors":0,

               "gifSessions":97,

               "photoSessions":56,

               "photosTaken":99,

               "photoEmails":36

       }

}

events:

[

       {"title":"Demo 1 Props & Filters","description":"","folder":"demo full","currentEvent":true},

       {"title":"Demo 2 Boomerang GIF","description":"","folder":"demo boomerang"},

       {"title":"Demo 3 Photo (no printing)","description":"","folder":"demo photo"},

       {"title":"Demo 4 Print Menu (printing)","description":"","folder":"demo menu"},

       {"title":"Demo 5 Surveys","description":"","folder":"demo surveys"},

       {"title":"Demo 6: AI Background Removal","description":"","folder":"AI Background Removal"}

]

 

The POST parameters are:

 

auth: SHA1 hash of the vendor id + time + password

hash: reserved for future use

time: the time since the Unix epoch - also used to calculate the SHA1 hash for the auth parameter

request: the HTTP POST request type. Currently this will always be "ipad status"

username: the user name if the iPad is logged in

name: the name of the iPad

model: the model of the iPad

user_id: a unique string identifying the username

id: the vendor id of the iPad - also used to calculate the SHA1 hash for the auth parameter

status: the status of the iPad or the screen currently being displayed when in photo booth mode

info: a JSON string providing more detailed information about the status of the app

 

Sending Commands to the iPad in the Response String

 

The web server can send a JSON string containing commands in the body of the response to the POST request.

WARNING: Please take care to validate the POST request (e.g. by only responding to known verndor ids and checking the auth parameter) before returning sensitive information such as the username and password

 

The following commands are currently supported:

 

JSON command

Description

{"cmd":"login","user":"<username>", "pw":"<password>"}

Login using the given username and password

{"cmd":"logout"}

Logout

{"cmd":"sync","method":"get","eventSyncServer":"<URL>"}

Sync using GET and the given sync server URL

{"cmd":"sync","method":"post","eventSyncServer":"<URL>","eventSyncServerPostPassword":"<password>"}

Sync using POST and the given sync server URL and password

{"cmd":"sync","method":"dropbox","dropboxPrefix":"<prefix>"}

Sync using Dropbox and the given Dropbox prefix

{"cmd":"start","event":<event_number>}

Start photo booth by running the given event. Set <event_number> to 0 to run the first event in the list of events, 1 to run the second event etc.

{"cmd":"exit"}

Exit photo booth mode and return to the start screen

{"cmd":"update"}

Sync the current event using the current sync settings

{"cmd":"updateAll"}

Exit photo booth mode and update all events using the current sync settings

{"cmd":"email", "to":"<email_addr>"}

Email the iPad's status together with a copy of the journal.txt file and the settings.xml file to the given email address. A screenshot can be included by adding "screenshot":true to the JSON response e.g. {"cmd":"email", "to":"<email_addr>", "screenshot":true}
The email server can be specified by adding the SMTP server, username, port number and password to the JSON response e.g. {"cmd":"email", "to":"<email_addr>", "server":"<smtp_server>", "port":<port_number>, "user":"<username>", "pw":"<password>"}

 

An optional "next" value can be added to the command to specify the interval in seconds before the next status update from the iPad (this overrides the <statusUpdateInterval> setting).

e.g. login and send next status update in 60 secs: {"cmd":"login","user":"<username>", "pw":"<password>", "next": 60}

 

Sample PHP Script for responding to status updates

 

The sample PHP script below shows how the status URL can be used to log information about the app status, log iPads in and send commands to iPads.

 

<?php

// ipad_status.php

//

// PHP script to log status information sent by iPads running Breeze Booth for iPad

// and to return commands to the iPad.

// To enable iPad status messages set the following tags in the settings.xml file on the iPad:

// <statusUrl>https://yoursite.com/ipad_status.php</statusUrl>

// <statusUpdateInterval>600<statusUpdateInterval>

//

// statusUpdateInterval is the update interval in seconds. Set this to 0 to disable updates.

// In version 1.1.2 of Breeze Booth for iPad the update interval can be overridden by adding

// a "next" value to the JSON response.

//

// Sample JSON data sent in the info argument:

// {

//         "version":"1.0.5",

//         "totalInMB":61035,

//         "availableInMB":36142,

//         "model":"iPad Pro 11\"",

//         "status":"Camera settings",

//         "battery":35,

//         "dropboxAccount":"me@mydomain.com",

//         "signedInAs":"username",

//         "date":"20191203",

//         "time":1575456854,

//         "timeZoneOffset":0,

//         "queues": {

//                 "dropboxQueue":0,

//                 "textQueue":0,

//                 "hubQueue":18,

//                 "uploadQueue":0,

//                 "emailQueue":0

//         },

//         "total": {

//                 "emailErrors":0,

//                 "photoTexts":1,

//                 "gifTexts":7,

//                 "gifEmails":118,

//                 "textErrors":0,

//                 "gifSessions":123,

//                 "photoSessions":653,

//                 "photosTaken":1596,

//                 "photoEmails":21

//         },

//         "today": {

//                 "emailErrors":0,

//                 "photoTexts":0,

//                 "gifTexts":0,

//                 "gifEmails":0,

//                 "textErrors":0,

//                 "gifSessions":2,

//                 "photoSessions":0,

//                 "photosTaken":0,

//                 "photoEmails":0

//         }

// }

 

// read arguments sent by iPad

$args = json_decode(file_get_contents('php://input'), TRUE);

$id = $args["id"];

$name = $args["name"];

$model = $args["model"];

$username = $args["username"];

$userId = $args["user_id"];

$request = $args["request"];

$time = $args["time"];

$hash = $args["hash"];

$status = $args["status"];

$info = $args["info"];

 

// list of iPad vendor ids and descriptions

$ipads = array(

    '95DFB8B0-2C03-4798-8473-2367709123454' => 'iPad Pro (2)',

    'E1234C79-8C00-4613-94A7-527C88CE7DD4' => 'iPhone 8 Plus',

    '45F4E97F-B4AB-1234-9664-AD105EF0AF94' => 'iPad 9.7 2018 cellular'

);

 

// append $msg to log file

function logMsg($msg)

{

    file_put_contents('../ipad_status_log.txt', gmdate('Y/m/d H:i:s: ') . $msg . PHP_EOL, FILE_APPEND | LOCK_EX);

}

 

// check the iPad's vendor id is one of your iPads

// return true if it is ok, false if not

function checkVendorId($id)

{

    // TODO: add extra code here to verify that the vendor id is one of your iPads not

    // someone else's which is trying to login to your account. A basic implementation

    // is shown below:

    global $ipads;

    if (array_key_exists($id, $ipads)) {

        return true;

    }

    return false;

}

 

// verify vendor id and password before sending login info back to the iPad

if (!checkVendorId($id))

{

    logMsg("Id: $id, Unknown vendor id");

    http_response_code(401);

}

else if ($time < time() - 60 || $time > time() + 60)

{

    // refuse the command if the time sent by the iPad isn't the time now +/- 60 secs

    logMsg("Id: $id, time error");

    http_response_code(401);

}

else if (sha1($id . " Breeze Systems " . $time . " [fudge] " . $userId) == $hash)

{

    // log JSON info to text file

    logMsg("Id: $id, info: $info");

 

    // decode JSON info and send login command to auto-login the iPad if it isn't currently logged in

    $json = json_decode($info, TRUE);

    if ($json["signedInAs"] == "")

    {

        // log the iPad in

        // change "username" and "password" to a username and password for your account

        $cmd = array('cmd' => 'login', 'user' => 'username', 'pw' => 'password', 'next' => 30);

        logMsg("Id: $id, logging in as " . $cmd['user'] . "...");

        echo json_encode($cmd);

    }

/*

    else if ($json["status"] == "Startup")

    {

        // you can also send other commands similar to the BlueTooth commands e.g.

        logMsg("Id: $id, sending start command...");

        $cmd = array('cmd' => 'start', 'next' => 30);

        echo json_encode($cmd);

    }

*/

    else

    {

        // everything is fine, request next update in 600 secs

        $cmd = array('next' => 600);

        echo json_encode($cmd);

    }

}

else

{

    logMsg("Id: $id, AuthFail");

    http_response_code(401);

}

?>