Integrating Piwik in iOS mobile applications

The Piwik platform is a free, powerful and open source tracking and analytics tool. It integrates well with most popular platforms, and is fairly easy to use. There are virtually no limitations or setbacks to using it, except perhaps the capabilities of the machine that it runs on. You can use it to track and calculate traffic, revenue, and many other things on your website. But why stop there? Why not use this powerful tool inside your mobile application? In this guide, I will show you how you can easily install a Piwik platform on your own server machine, and integrate a tracker in your iOS mobile application.

Prerequisites

Before we begin, make sure you already have the following things:

  • LAMP Server

    – A running server machine you have root/SU access to, running Linux, Apache, MySQL and PHP. You can also setup your Piwik MySql database on a different machine, as long as you have write access to it.

  • Target iOS app

    – A working iOS app you are developing, and would like to integrate your Piwik platform into. The device will need internet access to send data to your Piwik platform.

Installing Piwik on your server

First, you will need to upload the Piwik software onto your server. Download and unzip it from here. Then, you can upload it via your file browser, FTP client, or even the

wget

command from the terminal. To do this all in one step, simply use terminal to navigate to the target folder and run this command:

wget http://builds.piwik.org/piwik.zip && unzip piwik.zip

Make sure the folder you choose is accessible via a web browser!!
Afterwards, open your favorite web browser and navigate to the location of your piwik installation on the server: http://server-prefix/piwik-folder-path. This will take you to an installation wizard that will guide you through the installation and setup process of your Piwik platform:

  • Step 1: Welcome Screen

    welcome
    Just click “next”

  • Step 2: System Check

    System Check 1
    On this screen, you can make sure your server has all the desired software requirements installed. If there is a problem, Piwik will display it and tell you how to solve it, like this:
    System Check 2

  • Step 3: Database Setup

    MySQL DB Setup
    Make sure your login and password are for a user that has write access to the MySQL database.

  • Step 4: Create a Piwik Super User

    Super User

  • Step 5: Create your first website

    website
    Fill in details about the first website or app you wish to track.

Afterwards, just click “Next” twice more and Voila! Your Piwik platform is up and running on your server!
For more detailed information, refer to the Piwik installation guide.

Integrate The Piwik iOS SDK

You can download or “git clone” the Piwik SDK project from here. Afterwards, you need to add to add all of the source files and required frameworks (Core Data, Core Location, Core Graphics and UIKit) to your project’s build target.

If you use CocoaPods with your project, you can simply open your podfile and add the SDK as a dependency:

pod 'PiwikTracker'

for using the NSURLSession class to send requests to the Piwik API, or:

pod 'PiwikTracker/AFNetworking2'

for using AFNetworking2 to send requests to the Piwik API. Don’t forget to run

pod install

from the terminal!

Init The Piwik Tracker

Open your AppDelegate.m file, import the Piwik framework, and setup the tracker. Your modifications should look something like this:

#import <PiwikTracker/PiwikTracker.h>

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
//setup Piwik analytics tracker
    [PiwikTracker sharedInstanceWithSiteID: baseURL:[NSURL URLWithString:http://server-prefix/piwik-folder-path/piwik]]; //mind the "piwik" suffix!!
    [PiwikTracker sharedInstance].debug = NO; //YES to just write all requests to the console, NO to actually send the requests.
    [PiwikTracker sharedInstance].dispatchInterval = 0; //time interval (in seconds) between sending requests. 0 to send requests immediately.
    [PiwikTracker sharedInstance].eventsPerRequest = 1; //number of events to send per API request
}

Now, all that’s left is to choose the pages, views, buttons, and any other items or events you wish to track, and add the relevant tracking line of code to it:

//to set a user ID for the visitor
[[PiwikTracker sharedInstance] setUserID:@"John Smith"];

//to track the full screen/view hierarchy, i.e. screen/view1/view2/this-view (usually placed in the "viewDidAppear" method
[[PiwikTracker sharedInstance] sendViews:@"view1", @"view2", self.title, nil];

//to track custom events of app interaction
[[PiwikTracker sharedInstance] sendEventWithCategory:@"Documentary" action:@"Play" name:@"Thrive" value:@8.0];

//to track exceptions and errors
[[PiwikTracker sharedInstance] sendExceptionWithDescription:@"Oops, something went wrong!" isFatal:NO];

//to track when users interact with social networks
[[PiwikTracker sharedInstance] sendSocialInteraction:@"Like" target:@"cat.png" forNetwork:@"Facebook"];

//to track and measure popular keywords used for different search operations in the app
[[PiwikTracker sharedInstance] sendSearchWithKeyword:@"Galaxy" category:@"Books" numberOfHits:17];

//to track goals and conversion rate
[[PiwikTracker sharedInstance] sendGoalWithID:@"1" revenue:100];

//to track ecommerce transactions
PiwikTransaction *transaction = [PiwikTransaction transactionWithBuilder:^(PiwikTransactionBuilder *builder) {
  builder.identifier =
  [builder addItemWithSku: ... ]
  ...
  }];
[[PiwikTracker sharedInstance] sendTransaction:transaction];

//to track campaigns (usually placed in the "openURL" method of the AppDelegate.m file)
[[PiwikTracker sharedInstance] sendCampaign:(NSString*)campaignURLString;

// Track content impressions and interactions with ads and banners:
// Track an impression when the ad is shown
[[PiwikTracker sharedInstance] sendContentImpressionWithName:@"DN" piece:@"dn_image.png" target:@"http://dn.se"];
// Track an interaction when the user tap on the ad
[[PiwikTracker sharedInstance] sendContentInteractionWithName:@"DN" piece:@"dn_image.png" target:@"http://dn.se"];

That’s it! Your Piwik platform is up and running, and the app activity is being tracked.
To see your tracking data, just go to your Piwik platform: http://server-prefix/piwik-folder-path
Your dashboard should look something like this:
Piwik dashboard

From here, your options are endless.
For more information, visit the various Piwik API guides here.
For themes and plugins to further customize your Piwik platform and tailor it to your needs, visit the Piwik Marketplace.
To find out about other platforms, frameworks, and technologies Piwik can integrate with, visit the Piwik Integrations Page.

Enjoy! 🙂

One thought on “Integrating Piwik in iOS mobile applications

  1. I am sending a event with a category but i want to send more variables and their values with it along with action, name and value that is being sent.
    Basically I can set CustomVariables but cant track them.

Leave a Reply

Your email address will not be published. Required fields are marked *