Presentation upload specification

Updated on May 10, 2019

Orbitvu Station communicates between the online store and the application based on the specifications described below. Based on this specification, you can implement a similar mechanism for your own shop platform.

In a step 1 we should set any “cookie” on a HTTP Server (Orbitvu Station checks if under specified url “Set-Cookie” header is present, so the name of the cookie is irrelevant). Then we send a response to the Orbitvu Station in xml format:

<ovs_response>
<code>0</code>
<message>Authorization succeeded!</message>
<data>https://your_remote_upload_url?ov_action=upload</data>
</ovs_response>

In a step 2 Orbitvu Station will send a POST Request to the address: https://your_remote_upload_url?ov_action=upload with zipped (“.ovus”) Orbitvu Presentation. Then we send a response to the Orbitvu Station in xml format with status message.

Sample implementation

index.php file:

if (isset($_GET['ov_action']) && $_GET['ov_action'] == 'upload') {
   $archiveName = 'orbitvu_presentations'.DIRECTORY_SEPARATOR. $_FILES['path']['name'];
   $xml = new SimpleXMLElement('<ovs_response/>');
   if (copy($_FILES['path']['tmp_name'], $archiveName)) {
       $xml->addChild('code', 0);
       $xml->addChild('message', 'Upload succeed!');
   } else {
       $xml->addChild('code', 4);
       $xml->addChild('message', 'Upload failed!');
   }
   header('Content-Type: text/xml; charset=utf-8');
   print $xml->asXML();
   exit();
} else {
   setcookie('random_cookie', 'random_cookie_value', time() + 3600 * 3);
   $xml = new SimpleXMLElement('<ovs_response/>');
   $xml->addChild('code', 0);
   $xml->addChild('message', 'Authorization succeeded!');
   $xml->addChild('data', 'https://your_remote_upload_url?ov_action=upload');
   header('Content-Type: text/xml; charset=utf-8');
   print $xml->asXML();
   exit();
}

In the above example the Orbitvu Presentation will be saved in “orbitvu_presentations” folder. After successful uploading you need to unzip the Orbitvu Presentation using PHP class “ZipArchive” - it’s not shown in the example. When you unzip the presentation, its folder will contain content2.xml file where you will have the SKU of the presentation.

Sample implementation with authorization

index.php file:

define("OV_KEY", 'my_secret_key'); //secret key

if (!isset($_GET['ov_key']) || (OV_KEY !== $_GET['ov_key'])) {
   return xmlResponse(4, "Authorization URL is not complete, not valid or expired.");
}
if (!isSessionStarted()) {
   session_start();
}

if (isset($_GET['ov_action']) && $_GET['ov_action'] == 'upload') {
   if (!isset($_SESSION['ov_token']) || !isset($_GET['ov_token'])
       || ($_SESSION['ov_token'] != $_GET['ov_token'])) {
       return xmlResponse(4, 'Authorization failed!');
   }
   $archiveName = 'orbitvu_presentations'.DIRECTORY_SEPARATOR. $_FILES['path']['name'];
   $xml = new SimpleXMLElement('<ovs_response/>');
   if (copy($_FILES['path']['tmp_name'], $archiveName)) {
       setcookie('random_cookie', '', time() - 3600); //destroy cookie
       unset($_SESSION['ov_token']); //destroy ov_token
       return xmlResponse(0, 'Upload succeed!');
   } else {
       return xmlResponse(4, 'Upload failed!');
   }
} else {
   //generate token
   $token = md5(md5(date('Y-m-d H:i:s') . ' ' . mt_rand(1000, 10000)));
   $_SESSION['ov_token'] = $token;
   //set cookie for Orbitvu Station
   setcookie('random_cookie', 'random_cookie_value', time() + 3600 * 3);
   $uploadUrl = 'https://your_remote_upload_url?ov_action=upload&ov_key='.$_GET['ov_key'].'&ov_token='.$token;
   return xmlResponse(0, 'Authorization succeeded!', $uploadUrl);
}

/**
* Returns xml response
*
* @param int    $code
* @param string $message
* @param string $additionalData
*/
function xmlResponse($code, $message, $additionalData = '') {
   $xml = new SimpleXMLElement('<ovs_response/>');
   $xml->addChild('code', $code);
   $xml->addChild('message', $message);
   if ($additionalData !== '') {
       $xml->addChild('data', str_replace('&', '&amp;', $additionalData));
   }
   header('Content-Type: text/xml; charset=utf-8');
   print $xml->asXML();
   exit();
}

/**
* Checks if session is started
* @return bool
*/
function isSessionStarted() {
   if (php_sapi_name() !== 'cli') {
       if (version_compare(phpversion(), '5.4.0', '>=')) {
           return session_status() === PHP_SESSION_ACTIVE ? true : false;
       } 
       return session_id() === '' ? false : true;       
   }
   return false;
}

Remote upload url is: https://your_remote_upload_url?ov_key=my_secret_key
On the server side we check if $_GET[‘ov_key’] is the same as constant “ov_key” defined on the server.
If so, we generate unique token on a server and save it on a global $_SESSION[‘ov_token’] variable. We send a response to the Orbitvu Station with an upload url:
https://your_remote_upload_url?ov_key=my_secret_key&ov_token=generated_token&ov_action=upload
Orbitvu Station send another request to the server:
https://your_remote_upload_url?ov_key=my_secret_key&ov_token=generated_token&ov_action=upload
On the server side we check if $_GET[‘ov_key’] is proper and if $_GET[‘ov_token’] is the same as $_SESSION[‘ov_token’ .
If key and token are valid, we allow to upload presentation and destroy $_SESSION[‘token’]. After all we send a response to the Orbitvu Station.

Previous Article Shopify Migration

Next Article Introduction

Orbitvu Public Support Site

Presentation upload specification

Sample implementation

Sample implementation with authorization

e-Commerce integrations EN

Other Resources