NAV Navbar
iOS (Objective-C) iOS (Swift) Android

Introduction

Download The iOS SDK

Download The Android SDK

Welcome to the VenPath SDK! You can use our SDK to send anonymous data into the VenPath Global Marketplace for monetization.

Our SDKs are ruthlessly optimized for speed, reliability and low battery consumption. Also, we can take in any datatype that you have access to. If your app has access to a datatype that we don’t specifically mention in these docs, please reach out and we’ll make sure to add it to the docs.

Each SDK package includes sample apps so you can see how it can be done right in your IDE.

You can view code examples in the dark area to the right, and always feel free to reach out to developer support if you need a hand.

Installation

Here’s how to get installing started:

// There are 2 files you need to add to your xcode project:
//  * libVenPath.a
//  * VenPath.h

// Make sure the following frameworks are enabled in Build Phases -> Link Binary With Libraries:
// * AdSupport.framework
// * CoreLocation.framework
// * libVenPath.a

// Inside your application's AppDelegate.m, place the following import statement at the top:
#import "VenPath.h"
// There are 2 files you need to add to your xcode project:
//  * libVenPath.a
//  * VenPath.h

// Make sure the following frameworks are enabled in Build Phases -> Link Binary With Libraries:
// * AdSupport.framework
// * CoreLocation.framework
// * libVenPath.a

// Create a file called "VenPath-Bridging-Header.h" in your project with the following inside it:
#import "VenPath.h"

// Add the path to the bridge header file in your build settings under: "Objective-C Bridging Header"
// You have to import the AAR file in the project:
// Click on app module and right click -> new -> module
// Select the VenPath SDK AAR.

// Then, in your app's gradle file, you'll need this:
compile 'com.google.android.gms:play-services-location:11.6.0'
compile 'com.google.code.gson:gson:2.8.0

To install, you have to add the relevant files to your project.

Permissions

// For Android versions earlier than 21:
<uses-permission android:name="android.permission.INTERNET"/>

// And if you want to send location:
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>

If your app needs to prompt for specific permissions, make sure you do that :)

Permissions differ depending on what you want to send us, but at a minimum, you must be able to connect to the internet.

Location is a good one too.

Background location is a great one.

Authentication

To authorize, use this code:

// In order to initialize the SDK, add the following code to your "didFinishLaunchingWithOptions" function:
VenPath *venpath = [VenPath shared];

// And now, we auth.
[venpath sdkKey:@"bosskey" publicKey:@"lookatme" secretKey:@"shhhh"];
// To enable the shared lib put this in your appdelegate or view controller:
let venpath: VenPath = VenPath.shared();

// And now, we auth.
venpath.sdkKey("bosskey", publicKey: "lookatme", secretKey: "shhhh")
// Initialize
public class VenpathApplication extends Application
{
    @Override
    public void onCreate() {
        super.onCreate();


        boolean isTest;
        boolean isPassiveBackground;

        // If you are in development, set isTest = true;
        if(BuildConfig.DEBUG) {
            isTest = true;
        } else {
            isTest = false;
        }

        // If you want to enable passive background location mode, set isPassiveBackground = true;
        isPassiveBackground = false;

        // And now, we auth.
        VenPath.init(isTest, "bosskey", "shhhh", "lookatme", isPassiveBackground);
    }
}

// In your AndroidManifest.xml file, you need to name this class.
android:name=.VenpathApplication

Make sure to replace bosskey with your SDK key.

Make sure to replace lookatme with your Public key.

Make sure to replace shhhh with your Secret key.

We use a whole bunch of keys in our SDK.

Ok, 3. We use 3 keys.

They are your SDK key, Public Key and Secret Key.

If you don’t have any Keys yet, you can get them in the Connect portal.

Sending Data

Here’s where the real magic begins :)

We collect 2 main types of data:

  1. Location
  2. Everything Else

The “Everything Else” part is really just unstructured data, or “generic” data as we call it.

It can be anything - literally anything - that your app has access to & is able to monetize. If we think it might be valuable, we’ll take it.

The docs lay out the most popular types of “generic” data, but if you have something else, let us know and start sending it across.

Also, just because we want everything doesn’t mean you have to send it. Nothing is required!

Locations

// To set the current location for a user, place the following code snippet inside the didUpdateLocations method of your LocationManager Delegate:
CLLocation *venPathLocation = [locations lastObject]; [venpath trackLocation:venPathLocation];

// When your app is open, try to fire this every minute.
// When your app is closed, try to fire this every 5 minutes in the background.
// Or, on a SignificantLocationChange
// Use the following line in your location manager to send the data to us:
venpath.trackLocation(location);

// (location is an object of class CLLocation)

// When your app is open, try to fire this every minute.
// When your app is closed, try to fire this every 5 minutes in the background.
// Or, on a SignificantLocationChange
// Once you have permission to collect locations, use this line of code to get it:
venpath.trackLocation();

// That's it!  We'll take care of the rest.

Remember: Foreground collection is good but Background collection is great!

We love some location data. Foreground and especially background.

The best way to collect it is every minute in the foreground (when your app is open) and every 5 minutes in the background (when your app is closed.)

Alternatively on iOS, you can use a SignifantLocationChange event if you don’t have access to your app every 5 minutes in the background.

For Android, we include a passive background mode to collect on location change event - just like on iOS.

Don’t worry about fields. The SDK grabs everything it needs.

Collecting this frequently barely has any effect on the battery. “Average energy impact is low” is what XCode was saying. Seriously, I wouldn’t worry about it.

Email Match Pairs

// Let's get an instance of the VenPath object:
venpath = VenPath.getInstance(MainActivity.this);

// Now, let's send an email record across:
VenpathGeneric venpathGenericData =
        new VenpathGeneric().putVenpathGenericAttribute("email", "support@venpath.net")
                            .putVenpathGenericAttribute("timestamp", System.currentTimeMillis())
                            .putVenpathGenericAttribute("new_user", true);

venpath.setVenpathGenericData(venpathGenericData);

venpath.track(new VenPath.Callback() {
    @Override
    public void onSuccess(String result) {
        // Care to log it?  Up to you!
        LogUtils.d("Generic_App s", result);
    }

    @Override
    public void onError(String result) {
        // Care to log it?  Up to you!
        LogUtils.d("Generic_App  f", result);
    }
});
// Let's get the timestamp
NSNumber* timestamp = [NSNumber numberWithLongLong:(long long)([[NSDate date] timeIntervalSince1970])];

// Now, send a record across
[venpath track:@{
@"email": @"support@venpath.net",
@"timestamp": timestamp,
@"new_user": @"true"
}];
// Let's get the timestamp
let timestamp = Int64(date.timeIntervalSince1970 * 1000.0)

// Now, send a record across
venpath.track(["email":"support@venpath.net", "timestamp":timestamp, new_user":"true"])

Remember: Set “email” to the raw email. The SDK will hash it up automatically - The raw email NEVER gets sent to us!

For this data set, we take 2 fields:

email (required.)

The raw email address (which will be automatically encoded by the SDK before it gets transmitted.)

"email":"support@venpath.net"

timestamp (required.)

The unix timestamp or UTC Datestamp for this data point.

"timestamp":"1969-07-20 20:18:00"

"timestamp":1435809600

new_user

A flag that states if the user is new or not.

“true” means this is a new user / registration event.

“false” means it is not a new user / login event.

"new_user":true

"new_user":false

App Usage

If you can get running apps on the phone, you can track app usage. We DO NOT want it if it’s just your app - it has to be all on the phone.

// Let's get an instance of the VenPath object:
venpath = VenPath.getInstance(MainActivity.this);

// Now, let's send an app usage record across:
VenpathGeneric venpathGenericData =
        new VenpathGeneric().putVenpathGenericAttribute("event_date", System.currentTimeMillis())
                            .putVenpathGenericAttribute("event_type", "launch")
                            .putVenpathGenericAttribute("app_name": "com.facebook.orca")
                            .putVenpathGenericAttribute("seconds_used": "100")
                            .putVenpathGenericAttribute("permissions": "comma,delimited,list,of,apps,granted,permissions");

venpath.setVenpathGenericData(venpathGenericData);

venpath.track(new VenPath.Callback() {
    @Override
    public void onSuccess(String result) {
        // Care to log it?  Up to you!
        LogUtils.d("Generic_App s", result);
    }

    @Override
    public void onError(String result) {
        // Care to log it?  Up to you!
        LogUtils.d("Generic_App  f", result);
    }
});
// Let's get the timestamp
let timestamp = Int64(date.timeIntervalSince1970 * 1000.0)

// Now, send a record across
venpath.track([
    "app_name": "com.facebook.orca",
    "event_date": timestamp,
    "event_type": "launch",
    "seconds_used": "100",
    "permissions": "comma,delimited,list,of,apps,granted,permissions"
]);
// Let's get the timestamp
NSNumber* timestamp = [NSNumber numberWithLongLong:(long long)([[NSDate date] timeIntervalSince1970])];

// Now, send a record across
[venpath track:@{
    @"app_name": @"com.facebook.orca",
    @"event_date": timestamp,
    @"event_type": @"launch",
    @"seconds_used": @"100",
    @"permissions": @"comma,delimited,list,of,apps,granted,permissions"
}];

Remember to use a REAL DATA (unix timestamp or UTC Datestamp in YYYY-MM-DD HH:II:SS format for your “event_date”, the actual “app_name” as a package, the actual permissions, event_type, etc.

App Usage data is just what it sounds like. If you have access to all running apps on the device, we’d love to take a look :)

This data set takes in a bunch of points:

event_date (required.)

The unix timestamp or UTC Datestamp of when the event took place. It can also be a unix timestamp, if you’re so inclined.

"event_date":"1969-07-20 20:18:00"

"event_date":1435809600

event_type (required.)

The type of event we are recording. These are the valid event types:

  1. “install”: An app was installed.
  2. “update”: An app was updated.
  3. “delete”: An app was deleted or uninstalled.
  4. “launch”: An app was launched.
  5. “footprint”: This is part of a daily footprint of all apps installed on a device.
  6. “change”: A pre-installed app was enabled / disabled.

"event_type":"launch"

app_name (required.)

The name of the app in question (in package format.)

"app_name":"com.facebook.orca"

installed_version

The installed version of the app in question.

"installed_version":"1.4.21"

seconds_used (required for ‘launch’ event_type.)

The time the app was opened, in seconds. This is only valid for a “launch” event_type.

"seconds_used":24

permission

This is a text field for all of the permissions the app_name currently has on the phone.

"permission","android.permission.RECEIVE_BOOT_COMPLETED,android.permission.INTERNET,android.permission.ACCESS_NETWORK_STATE,android.permission.VIBRATE,android.permission.WAKE_LOCK,android.permission.READ_EXTERNAL_STORAGE,android.permission.WRITE_EXTERNAL_STORAGE,com.android.alarm.permission.SET_ALARM,android.permission.GET_ACCOUNTS,com.android.vending.BILLING"

Capturing Install / Delete / Update Events

When capturing app events, you simply have to place your setVenpathGenericData() call inside of an event handler. You can grab install, update and delete events like this.

Capturing Launch Events

To capture a launch event, you have to use logic similar to this:

Launch the app for the first time -> Build a database of running apps -> Mark these as seconds_used = 0 -> launch a process every second -> Get list of running apps -> If app is already on the list, seconds_used = seconds_used + 1 -> else, seconds_used = 0 -> If an app is no longer running, remove it from the database and send it with track()`

Sending App Usage Data

To send data accumulated in setVenpathGenericData(), make sure you call track() when appropriate based on your app.

The goal is to try to send it once per hour, if you can.

// Let's get an instance of the VenPath object:
venpath = VenPath.getInstance(MainActivity.this);

// Now, let's send search across:
VenpathGeneric venpathGenericData =
        new VenpathGeneric().putVenpathGenericAttribute("search_terms", "venpath")
                            .putVenpathGenericAttribute("search_category", "documentation")
                            .putVenpathGenericAttribute("search_category_keywords", "data,monetization,collection")
                            .putVenpathGenericAttribute("search_location", "11203")
                            .putVenpathGenericAttribute("search_min", "2")
                            .putVenpathGenericAttribute("search_min", "15")
                            .putVenpathGenericAttribute("timestamp", System.currentTimeMillis());

venpath.setVenpathGenericData(venpathGenericData);

venpath.track(new VenPath.Callback() {
    @Override
    public void onSuccess(String result) {
        // Care to log it?  Up to you!
        LogUtils.d("Generic_App s", result);
    }

    @Override
    public void onError(String result) {
        // Care to log it?  Up to you!
        LogUtils.d("Generic_App  f", result);
    }
});
// Let's get the timestamp
NSNumber* timestamp = [NSNumber numberWithLongLong:(long long)([[NSDate date] timeIntervalSince1970])];

[venpath track:@{
    @"search_terms": @"venpath",
    @"search_category": @"documentation",
    @"search_category_keywords": @"data,monetization,collection",
    @"search_location": @"11203",
    @"search_min": @"2",
    @"search_max": @"15",
    @"timestamp": timestamp
}];
// Let's get the timestamp
let timestamp = Int64(date.timeIntervalSince1970 * 1000.0)

venpath.track([
    "search_terms":"venpath",
    "search_category":"documentation",
    "search_category_keywords":"data,monetization,collection",
    "search_location":"11203",
    "search_min":"2",
    "search_max":"15",
    "timestamp":timestamp
])

For this data set, we take 6 fields.

timestamp (required.)

The unix timestamp or UTC Datestamp of the event.

"timestamp":"1969-07-20 20:18:00"

"timestamp":1435809600

search_terms (require unless search_category or search_category_keywords is set.)

This is what the user searched for.

"search_terms":"data"

search_category (require unless search_category_keywords or search_terms is set.)

This is the category that was searched.

"search_category":"tacos"

search_category_keywords (require unless search_category or search_terms is set)

These are the keywords that were used in the search.

"search_category_keywords":"al pastor,chorizo,crispy fish"

search_location

This is the location where the user is searching. It can be a string (like a city) or a number (like a zip or postal code.)

"search_location":"brooklyn" "search_location":"11203"

search_min

This is the maximum range of the search.

"search_min":"0"

search_max

This is the maximum range of the search.

"search_min":"100"

Testing

Set this flag to see more debug info and separate your testing data from production data

// In your Application class, you can set your test before you call VenPath.init()
boolean isTest;

// If you are in development, set isTest = true;
if(BuildConfig.DEBUG) {
    isTest = true;
} else {
    isTest = false;
}

VenPath.init(isTest, "bosskey", "shhhh", "lookatme", isPassiveBackground);

// Remember:  Set isTest = false before you go live.
// Set the debug flag to YES before call track() or trackLocation()
venpath.debug = YES;

// Comment it out, or just delete the line before you go live.
// Set the debug flag to YES before call track() or trackLocation()
venpath.debug = YES;

// Comment it out, or just delete the line before you go live.

Remember to remove it before you push your app live!

If you put the SDK in debug or testing mode, you can see your testing data in real time and see event logs as they happen (like exceptions, which are normally hidden.)

To view your test data in real time, check out the SDK Test page in Connect.

That page will show you the last 100 points as they come in. Once you push live though, you should check out the SDK Status page in connect to verify that everything is flowing nicely.

Errors

The VenPath SDK uses the following errors:

Error Meaning
Unable to authenticate. Please check your keys. (400) Your Public and / or Secret key are wrong
Empty IDFA / AAID The Advertising ID is missing.
connectionError If sending the packet failed
SDK Key missing You forgot to put in your SDK key
Public Key missing You forgot to put in your public key
Secret Key missing You forgot to put in your secret key
Failed to grab IP from Venpath Service Pretty self explanatory… we tried to get the public IP of the device and it failed
Rate Limited We appreciate the enthusiasm, but you’re sending data too frequently
No data to send You tried to send data, but there wasn’t any set