Mobile SDK

The Parse.ly Mobile SDKs are small code libraries that you include in your mobile apps in order to track reader activity in mobile devices. There are currently libraries for Android (Java) and iOS (Objective-C). You can find the toolkits and installation instructions on Github:

You can also read detailed documentation of the toolkits here:

Proxy Server Protocol

The Parse.ly pixel server accepts GET requests containing the information for single actions. For mobile devices, sending one request per action wastes battery.

The Parse.ly SDK sends batches of events to a proxy server, which then splits the batches into individual requests for consumption by the pixel server. The SDK creates this batched request for you, but there are some cases where you might want to construct this batched request yourself.

Elements of the Proxy Request

All POST requests sent to http://srv.pixel.parsely.com/mobileproxy must have a single argument rqs. All other aruments are ignored.

The value of the rqs (requests) parameter is a URL-encoded JSON document that must have the following structure:

{
    "data":{
        "idsite":"samplesite.com",
        "parsely_site_uuid":"76e4c7f0afeb4e7643f5089235779937d9637b55",
        "appname":"ParselySDK",
        "manufacturer":"Apple",
        "os":"iPhone OS",
        "os_version":"6.1",
    },
    "events":[
        {
            "url":"http://samplesite.com/2013/03/20/obama-delinquent-with-budgets-always-on-time-with-ncaa-brackets-say-republicans/",
            "ts":1363796913.105937
        },
        {
            "url":"http://samplesite.com/this/is/a/real/post.html",
            "ts":1363596915.229876
        },
        {
            "url":"http://samplesite.com/2013/03/18/the-spin-does-not-stop-here/",
            "ts":1363296917.195734
        }
    ]
}

The data variable is a document containing invariant data about the pixel requests -- that is, data that is constant for all of the events being transmitted.

The events variable is a list of documents containing data that differs per request.

Variable Container Description Required Example
idsite data The site ID where data should be stored (API key) yes "idsite":"samplesite.com"
parsely_site_uuid data The UUID for the current user or device yes "parsely_site_uuid":"76e4c..."
appname data The name of the current app (for mobile devices) no "appname":"MyCoolApp"
manufacturer data The device manufacturer (for mobile devices) no "manufacturer":"Apple"
os data The name of the operating system (mobile only) no "os":"iPhone OS"
os_version data Operating system major and minor version no "os_version":"6.1"
url events The canonical URL of the tracked post yes "url":"http://samplesite.com/1234"
ts events The UNIX timestamp (seconds since epoch) yes "ts":1363796913.220884

A real request to the proxy server might look like this one, which contains two separate pageview events in the URL-encoded JSON document:

POST /mobileproxy HTTP/1.1
Host: srv.pixel.parsely.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 213

rqs=%7B%22data%22%3A%7B%22os_version%22%3A%226.1%22%2C%22appname%22%3A%22HiParsely%22%2C%22parsely_site_uuid%22%3A%22ad926df27f7f39fe1417f41bac9ec8e40232680a%22%2C%22idsite%22%3A%22somesite.com%22%2C%22manufacturer%22%3A%22Apple%22%2C%22os%22%3A%22iPhone%20OS%22%7D%2C%22events%22%3A%5B%7B%22url%22%3A%22http%3A%5C%2F%5C%2Fsomesite.com%5C%2Fnot-a-real-url.html%22%2C%22ts%22%3A1363977322.65788%7D%2C%7B%22ts%22%3A1363977323.012882%2C%22url%22%3A%22http%3A%5C%2F%5C%2Fsamplesite.com%5C%2Fthis%5C%2Fis%5C%2Fa%5C%2Freal%5C%2Fpost.html%22%7D%5D%7D

Generating a UUID

On desktop browsers, you can avoid generating a UUID by using the Parse.ly network UUID.

Mobile apps that use the Parse.ly toolkit don't have to create their own UUIDs, as the SDK handles that. However, if you'd like to create your own, it must be guaranteed to be unique per device.

The easiest way to guarantee uniqueness is to generate a UUID using the device MAC address. On iOS, see the CFUUIDCreate() function for a description of how to do this. Another good UUID might be an internal userid which might be used for tracking logged-in users.

If your UUID is not looked up in a remote database, you should save it in persistent storage (for example, iOS' NSUserDefaults key-value store).