====== PHP SDK version 1.1.0 ====== The PHP SDK is a relatively straightforward encapsulation of the Secure-eBook XML API. The definition for all SDK error codes can be found here: * [[sdk:error|Secure-eBook SDK Error Codes]] ===== Download ===== [[http://www.secure-ebook.com/seb_php_sdk_1_1_0.zip|Download PHP SDK v1.1.0]] ===== Step 1 - Including the SDK in your PHP project ===== In order to use the object, you must download the API and //include// the SDK in your PHP project. **Example** // Include the PHP SDK. Make sure the specified path fits your custom configuration. require_once('sebSDK.php'); ===== Step 2 - Instantiating the SDK ===== The SDK is encapsulated in a simple to use class. The class name is //SebSDK//. ==== Secure-eBook SDK Constructor ==== function SebSDK($vendorCode, $sdkKey, $testMode = false, $sdkURL = false) ... ^Parameter^Name^Description^ |$vendorCode|The Secure-eBook vendor code|This code identifies the account under which the activation keys and download links will be generated. The Vendor Code can be found in the Secure-eBook Account Information. Look for //Vendor Code// in My Account -> Account Information.| |$sdkKey|The Secure-eBook SDK secret keyword|This keyword must be set in your Secure-eBook account. The keyword is known by Secure-eBook and the third party application and is used to validate the identity of the software using the SDK. Look for //SDK Secret Keyword// in My Account -> Account Information. %%[%%[[:sdk_config|more]]%%]%%| |$testMode|Enable test mode|Disabled by default. If turned on, the whole activation/download link process will work, but no actual keys or links will be generated and tokens will consumed from the vendor account. This mode is to help you test your integration with Secure-eBook SDK| |$sdkURL|The URL of the Secure-eBook SDK|Allows to connect to an alternative server. At the time of this documentation, no alternate Secure-eBook servers are available.| **Example** // Create a SDK instance for account ADMI4176 in test mode. $sdk = new SebSDK("ADMI4176", "a#$%^#6vkl3", true); ===== Step 3 - Request Activation Keys / Secured Download Links ===== The SDK allows you to request multiple keys and links in one transaction. This is done through the //request// method of the //SebSDK// class. Whether keys, links or both are returned is based in the product's configuration in its linked Secure-eBook account. function request($products, $secureebookproductcode = true, $userdata = false, $orderinfo = false) ^Parameter^Name^Description^ |$products|Array of product information|The product array is composed of any number of **strings** representing the Product Code for which a key or link is requested and **arrays** in which the first item is the Product code and the second item is the number of keys or links required. When no quantity is specified, 1 is always assumed.| |$secureebookproductcode| true,false|If set to "true", the specified product codes will be considered as Secure-eBook product codes. If set to "false", product codes will be considered as shopping cart product codes.| |$userdata|String that identifies your transaction|Optional. Will be stored with the transaction information in Secure-eBook| |$orderinfo|Associative array containing order information|Optional. Information specified here will be stored with the transaction information in Secure-eBook. Accepted values are //name//, //email//, //country// ([[http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2|2 char. ISO 31661 country code]], //stateprov// (state or province), //note//, //total// (incl. taxes), //taxes//, //currency// (USD, CAD, GBP, AUD), //description//| **Example** $keys = $sdk->request( array('TEST', array('TEST2', 2)), // Request one key for book 'TEST' and two keys for book 'TEST2' true, // Uses the Secure-eBook product's code. 'order1', // Our system labels this order as 'order1', which will be stored on the Secure-eBook server. array('name' => 'John Doe', // We also send the client's name and email address. 'email' => 'johndoe@nowhere.com') ); ===== Step 4 - Analysing Results ===== If all goes well, the //request// method returns an array containing activation keys and/or download links. However, if something goes wrong, it will return //false//. Error codes and messages can be retrieved through the //SebSDK// class' //last_error// and //last_error_id// fields. |last_error|Gives a textual representation of the error| |last_error_id|Gives a numerical representation of the error, allowing you to customize the feeback you want to show. Error codes are described in the definition of the **[[error]]** XML SDK response.| **Example** if ($res === false) // triple equal makes sure that we are really looking for 'false' { echo "Error " . $sdk->last_error . " (" . $sdk->last_error_id . "}"; } ===== Step 5 - Receiving keys, links and Warnings ===== The //request// method returns an associative array (map) containing keys and warnings. ==== Receiving keys ==== The keys returned by the //request// method are stored in an array. This array is obtained by accessing the 'keys' value of the returned results. The elements of this array are associative arrays in which the following values have been set: |productcode|The Secure-eBook product's code or the Shopping Cart product’s code to which the key is bound| |key|An activation key| :!: Since Secure-eBook does not send emails for transactions that go through the SDK system, we strongly suggest that all proper activation and troubleshooting information is given to customers. The activation guide can be found here: http://secure-ebook.com/help/ebook_activation\\ Troubleshooting guide can be found here: http://secure-ebook.com/help/ebook_activation_assistance ==== Receiving Links ==== The links returned by the //request// method are stored in an array. This array is obtained by accessing the 'links' value of the returned results. The elements of this array are associative arrays in which the following values have been set: |productcode|The Secure-eBook product's code or the Shopping Cart product’s code to which the key is bound| |url|A secured download link| |expiration|A date in 'YYYY-MM-DD' format, in GMT time zone after which the link will be disabled.| |max_downloads|The number of times a download attempt can be made through this link. After the file download has been initiated this number of times, the link will be disabled.| :!: Since Secure-eBook does not send emails for transactions that go through the SDK system, we strongly suggest that all proper activation and troubleshooting information is given to customers. The activation guide can be found here: http://secure-ebook.com/help/ebook_activation\\ Troubleshooting guide can be found here: http://secure-ebook.com/help/ebook_activation_assistance ==== Receiving Warnings ==== The warnings returned by the //request// method are stored in an array. This array is obtained by accessing the 'warnings' value of the returned results. The elements of this array are associative arrays in which the following values have been set: |productcode|The Secure-eBook product's code or the Shopping Cart product’s code to which the warning is related to.| |messageid|Gives a numerical representation of the error, allowing you to customize the feeback you want to show. Error codes are described in the definition of the **[[success]]** XML SDK response.| |text|Gives a textual representation of the warning| ==== Example ==== if ($res === false) // triple equal makes sure that we are really looking for 'false' { echo "Error " . $sdk->last_error . " (" . $sdk->last_error_id . "}"; } else { if ( $res['keys'] ) { foreach($res['keys'] as $key) { echo $key['productcode'] . ' = ' . $key['key'] . '
'; } } // Generated links are returned here if ($res['links']) { foreach($res['links'] as $link) { echo "Link " . $link['url'] . " for " . $link['productcode'] . "
"; } } if ( $res['warnings'] ) { foreach($res['warnings'] as $warning) { echo $warning['productcode'] . ' = ' . $warning['messageid'] . '
'; echo $warning['text'] . "
"; } } } ====== Advanced Integration Techniques ====== * [[sdk:php-proxy|Allowing Proxy Settings through PHP SDK]] ---- [[sdk:php-history|PHP SDK Version History]]