Developers Licensing API (Remote Keys)

The SlideME Developer Licensing API allows developers to hook into the SlideME payments system in order to generate dynamic license keys for their applications. Compared to static keys that you can add on slideme.org in the app inventory page, dynamic license keys allow developers to generate license keys that are locked to the device on which the application was installed (using the device_mac/device_imei information provided by the API). Similar to static license keys (or application tokens), SlideME will include dynamic license keys in the invoice delivered to users.

How can I use the Developer Licensing API?
In order to use the Developer Licensing API, you (the developer) will have to successfully complete the following steps:

  1. On one of your web servers setup a License Server that follows the specification described below. In order to assist you in this task, SlideMe provides you with an PHP template file that you can easily customize to your needs.
  2. On slideme.org, access your application inventory page and add Remote license keys (fill in the License Server URL and quantity of license keys). SlideME will ping the Licensing Server you provided upon submission and will start using it on the next purchase.

How can I protect access to my Licensing Server?
You can setup Basic HTTP authentication, use some secret key in the query string of the Licensing Server URL, and/or block IPs that do not belong to SlideME. (Contact us for the latest list of IPs.)

If you use Basic HTTP authentication, fill in the Licensing Server URL in the following format:
http://username:password@yourserver.example.com/path/to/license.php

If you use a secret key in the query string, fill in the Licensing Server URL in the following format:
http://yourserver.example.com/path/to/license.php?your_query_string_data

Licensing Events

Events are specific requests that slideme.org will make to the License Server URL you provided for your application at various moments of the transaction lifetime. The current version (1.0) of the Developer Licensing API defines three types of events: ping, acquire, and release. The event name/type is sent in the action parameter of the request.

All events are sent as HTTP GET requests to your server. Requests contain various data about the transaction context and expect a JSON-formatter object in response. The object should contain the version property (currently set to value “1.0”).

Events fields

Events data include information about the application, developer, transaction and mobile device related to that event.

  • developer: is the username you use to log into slideme.org
  • developer_id: is the developer unique ID on slideme.org
  • application: is the name of the application retrieved from the APK file (the title of the application’s page on slideme.org)
  • application_id: is the application unique ID on slideme.org
  • package_name: is the application’s package name (from the apk manifest)
  • version_name: is the application’s version name (from the apk manifest)
  • transaction_id: is the transaction unique ID on slideme.org
  • price: is the price the buyer paid for the application (as set by the developer); the developer might receive lower value payments, due to taxes and processing fees that slideme.org pays to third parties.
  • currency: is the currency of the application price
  • device_id: generic ID of the device used to buy the application
  • device_mac: MAC of the device used to buy the application (could be empty)
  • device_imei: IMEI of the device used to buy the application (could be empty)
  • licensekey: license key sent back to the License Server (see release event)
Ping event

The ping event is used by slideme.org to test your Licensing Server availability and compatibility with the current version of the API. This event can be sent at any moment by slideme.org, and it contains fake information about a transaction and mobile device. The information about the application and developer are correct (as if they would be on a real transaction).

The ping events contain the following data (described above):
action, developer, developer_id, application, application_id, package_name, version_name, transaction_id, price, currency, device_id, device_mac, device_imei.

The device_id and device_imei are always 123456789012345. On a ping event, the License Server must respond with HTTP code 200 and the JSON-formatter object must include a data property containing the license key equal to application_id-transaction_id (e.g. 163-53343).

An example of Ping event data is:
http://example.com/remotelicenseserver?action=ping&developer=someone&developer_id=123&application
=SomeApp&application_id=163&transaction_id=1193246912&
package_name=org.slideme.someapp&version_name=1.0.3&
price=0.79&currency=USD&device_id=123456789012345&
device_imei=123456789012345

An example of response data is:
{"version":"1.0","data":"163-1193246912"}

Acquire event

The acquire event is similar (as data sent/replied) to the ping event. It marks a real transaction for which the Licensing Server should provide a license. The license key will be included in the user’s invoice and can contain up to 32 characters.

The acquire events contain the following data:
action, developer, developer_id, application, application_id, package_name, version_name, transaction_id, quantity, price, currency, device_id, device_mac, device_imei.

An example of Acquire event data is:
http://example.com/remotelicenseserver?action=acquire&developer=someone&developer_id=123&
application=SomeApp&application_id=163&transaction_id=
1193246912&package_name=org.slideme.someapp&version_name=
1.0.3&price=0.79&currency=USD&device_id=AB0212102202&
device_mac=AB0212102202

An example of response data is:
{"version":"1.0","data":"XLIV-2302"}

Release event

On some occasions, a license key needs to be canceled (because the user asked for a refund, his credit was bad, he switched devices, etc). In such a case, if slideme.org already acquired a dynamic license from your site, it will send you a release event for that license key (stored in the licensekey parameter). You can ignore this event or you can dispose of the license key by any means you want (e.g. store it in an “expired keys” database).

The release events contain the following data:
action, developer, developer_id, application, application_id, package_name, version_name, transaction_id, price, currency, device_id, device_mac, device_imei, licensekey.

An example of Release event data is:
http://example.com/remotelicenseserver?
action=release&developer=someone&developer_id=123&
application=SomeApp&application_id=163&
transaction_id=1193246912&package_name=
org.slideme.someapp&version_name=1.0.3&price=0.79&
currency=USD&device_id=AB0212102202&device_mac=
AB0212102202&licensekey=XLIV-2302

An example of response data is:
{"version":"1.0"}

Template of Licensing script

You can find a simple example of a licensing server script here. This script is provided only as an example to be use as a guide or to be extended. Do not use it directly unless you understand how it works and you are sure it fits your needs.

For further help, you may contact SlideME Support from http://SlideME.org/contact

You may follow us as a developer on: twitter.com/slidemedev or our general stream @ twitter.com/slideme

Further information and updates can be found at
http://slideme.org/developers