NAV Navbar
Swift Java JavaScript Ionic

Introduction

Welcome to SmartKarrot! Lookup the features and SDKs you can integrate into your apps.

  1. Usage analytics
  2. App analytics

SmartKarrot offers SDKs and private REST APIs for all its SaaS services. Our SDKs and APIs make it easy to quickly configure and integrate otherwise complex functionalities like referrals, user segmentation, geofencing, actions like rich push, gamification, surveys and feedback, analytics, donations, a full-fledged journey designer, wallets for cryptocurrency and fiat currency, and smart contracts on public and permissioned blockchains.

We have language bindings in Swift, Java, and JavaScript! You can view code examples on the right by selecting a programing language of your choice.

Development Quickstart

Integrating the SmartKarrot API requires only four quick steps:

  1. Get your API keys.
  2. Add our SDK to your app.
  3. Configure the SmartKarrot integration.

Prereqiusites

If you haven't already signed up on Smartkarrot platform for an SES Login account, then please do so by clicking here.

Once you have completed the sign up process and log on to the platform, you will be required to add an app to your account. Please go ahead and add the app that you want to capture analytic data for.

If you already have an account, click here to sign in.

Step 1: Get Your API Keys (AppId)

Add an app in the Settings section and find the API keys(AppID) under App details.

Step 2: Add our SDK to Your App

SmartKarrot provides iOS, Android and Web (JavaScript) SDKs.

# Run Script

APP_PATH="${TARGET_BUILD_DIR}/${WRAPPER_NAME}"

# This script loops through the frameworks embedded in the application and
# removes unused architectures.
find "$APP_PATH" -name '*.framework' -type d | while read -r FRAMEWORK
do
    FRAMEWORK_EXE_NAME=$(defaults read "$FRAMEWORK/Info.plist" CFBundleExecutable)
    FRAMEWORK_EXE_PATH="$FRAMEWORK/$FRAMEWORK_EXE_NAME"
    echo "Executable is $FRAMEWORK_EXE_PATH"

    EXTRACTED_ARCHS=()

    for ARCH in $ARCHS
    do
    echo "Extracting $ARCH from $FRAMEWORK_EXE_NAME"
    lipo -extract "$ARCH" "$FRAMEWORK_EXE_PATH" -o "$FRAMEWORK_EXE_PATH-$ARCH"
    EXTRACTED_ARCHS+=("$FRAMEWORK_EXE_PATH-$ARCH")
    done

    echo "Merging extracted architectures: ${ARCHS}"
    lipo -o "$FRAMEWORK_EXE_PATH-merged" -create "${EXTRACTED_ARCHS[@]}"
    rm "${EXTRACTED_ARCHS[@]}"

    echo "Replacing original executable with thinned version"
    rm "$FRAMEWORK_EXE_PATH"
    mv "$FRAMEWORK_EXE_PATH-merged" "$FRAMEWORK_EXE_PATH"

done

iOS App

You can install the SDK using CocoaPods or as a dynamic framework.

For installing using CocoaPods, add the line pod 'SmartKarrot-Core' to your Podfile and install it with pod install. Current version of the SDKs is 4.2.0.

If you want to add the SDK as a dynamic framework, download it.

  1. Add it to your Xcode project's Embedded Binaries.
  2. Select Build Phases, add a Run Script with shell as /bin/sh and script as given in the code section.

Android App

allprojects {
  repositories {
    // add this repository at the bottom of the repositories list
    maven { 
      url "https://s3.amazonaws.com/smartkarrot-android-repo/"
    }
  }
}

The Android SDK comes as a Java library. Installing it is simple. Just add the lines to the right to your project level build.gradle file.

Then add these lines to your App's build.gradle file:

implementation 'com.smartkarrot:usageanalytics:0.0.4.6'

If you are supporting android versions before Lollipop (21), you need to add this line in your app's build.gradle file: multidexEnabled true

More info here: Enabling Multidex

Proguard Configuration

If you are using proguard in your app, add this configuration in your proguard-rules.pro file:

-keep class com.smartkarrot.** { *; }

-keepclassmembers class com.smartkarrot.** { *; }

Web - JavaScript

Add the following code in head tag of your HTML page.

<script src="https://docs.smartkarrot.com/frameworks/web/v4/UsageAnalytics.js"></script>

Angular: Declare declare var UsageAnalytics; to access UsageAnalytics from angular component.

Hybrid - Cordova/PhoneGap/Ionic Plugin

  1. Download SmartKarrot Plugin, download.

  2. Add SmartKarrot plugin to your app.

    Cordova plugin add SmartKarrot

    After adding you will see an entry in config.xml

    <plugin name="SmartKarrot" spec="SmartKarrot" />

  3. Declare the cordova plugin in the app page where this has to be used.

declare let cordova:any;

Step 3: Configure the SmartKarrot Integration

The SmartKarrot SDK must be initialized before using any of its functions.

iOS App

Import the SDK with into AppDelegate.swift file with

import UsageAnalytics

Add this to your AppDelegate.swift file

UsageAnalytics.shared.configure(appId: "app-id")

If you have a user Id available for the user of your app, you can configure the user Id together with the app Id with:

UsageAnalytics.shared.configure(appId: "app-id", userId: "user-id")

Android App

Add this line to the onCreate method of your activity or Application class.

UsageAnalytics.init(context, "app-id")

Web - JavaScript

Add the following javascript to your HTML page to initialize the SDK.

UsageAnalytics.configure("app_api_key")

Hybrid - Cordova/PhoneGap/Ionic Plugin

The plugin has to be initialized in the code after the view is loaded i.e. in the life cycle event ionViewDidEnter

ionViewDidEnter() { this.configureSmartKarrot(); }

configureSmartKarrot() { let appId = "your-app-id"; let userId = "your-app-user-id";

var successCallBack = function (successResult) { console.log(successResult); }

var failureCallBack = function (errorResult) { console.log(errorResult); }

cordova.plugins.SmartKarrot.configure(appId, userId, successCallBack, failureCallBack); }

Replace the appId & userId with actual values

Usage Analytics

This section describes how you can send usage analytics data to SmartKarrot. SmartKarrot helps you collect three types of usage data:

  1. User information
  2. Event information

The SDK caches events when an Internet connection is not available. The SDK uses a store-and-forward buffer to send events and user and device information every 120 seconds to minimize impact on power usage.

Set User Id

UsageAnalytics.shared.set(userId: "your-app-user-id")
UsageAnalytics.getInstance().setUserId("your-app-user-id");
UsageAnalytics.setUser("your-app-user-id");
cordova.plugins.SmartKarrot.setUserId(your-user-id, successCallback(), failureCallback());

SmartKarrot treats a user as a "guest" user - with an internally generated user Id, until you set a user Id. Once you set the user Id, the guest user is considered as having logged in as that user. Events logged of the guest user are transferred to the logged in user.

Reset User Id

UsageAnalytics.shared.resetUserId()
UsageAnalytics.getInstance().resetUserId();
UsageAnalytics.resetUser();
cordova.plugins.SmartKarrot.resetUserId(successCallback(), failureCallBack());

Reset the user Id when the user has logged out of the system. SmartKarrot logs events generated after the reset as a guest user.

Log Events

// Log without event attributes.
UsageAnalytics.shared.log(event: "Signed In")

// Log with event attributes.
UsageAnalytics.shared.log(event: "Screen View", with: ["Screen Name": "News List Screen"])

// Log with event attributes.
UsageAnalytics.shared.log(event: "Purchased Product", with: [
    "Module" : "Sales", // Standard Event Attribute
    "Product Id": "B01M3TD8CF", 
    "Deliver to ZIP Code": "07120-4719",
    "Quantity": 3,
    "Order Date": Date(),
    "Discount Applied": true
])
// Log without event attributes.
UsageAnalytics.getInstance().logEvent("Signed In");

// Log with event attributes.
EventParameters params = new EventParameters.Builder()
    .addParameter("Module", "Sales") // Standard Event Attribute
    .addParameter("Product Id", "B01M3TD8CF")
    .addParameter("Deliver to ZIP Code", "07120-4719")
    .addParameter("Quantity", 3)
    .addParameter("Order Date", new Date())
    .addParameter("Discount Applied", true)
    .build();
UsageAnalytics.getInstance().logEvent("Purchased Product", params);
// Log without event attributes.
UsageAnalytics.logEvent("Signed In");

// Log with event attributes.
var eventParams = {
    "Module" : "Sales", // Standard Event Attribute
    "Product Id": "B01M3TD8CF",
    "Deliver to ZIP Code": "07120-4719",
    "Quantity": 3,
    "Order Date": new Date().toISOString(),
    "Discount Applied": true
}
UsageAnalytics.logEvent("Purchased Product", eventParams); 
cordova.plugins. SmartKarrot.logEvent("Purchased Product", value, successCallback(), failureCallback())

 # Where “value” is a string and can also accept stringify(d) json object. 

You can log screen views and other events to SmartKarrot. Examples of app events are the user opening a screen, purchasing a product or logging in. The SDK automatically logs events like the user opening the app and closing it. You can add your events using our SDK.

A good place to add the screen view event is the viewDidAppear method of the view controller.

The SDK sends events to the server in a low priority queue, so user functionality is not affected. Events are buffered and sent every 120 seconds to reduce constant network traffic. When an internet connection is not available, the SDK automatically stores and forwards events.

SmartKarrot has a standard event attribute, aka, Module.

Note: Name of standard attributes needs to be passed exactly the way they are defined on this docs.

App Analytics

Loyalty Index

Loyalty Index is a measure of the percentage of user churn, i.e. the percentage of total users uninstalling the app to the total users installing the app in a given time period. If you have to enable Loyalty Index for your app, you need to add the following lines of code:

Enabling Loyalty Index for iOS

To enable Loyalty Index for your iOS app, you need to submit your Apple Push Notification certificates. There is a detailed step by step guide to generate them: external link After generating the certificates, submit the Dev & Prod certificates in .p12 format wihle app on boarding.

On your app side, add the following lines of codes:

// Add these functions to your AppDelegate file

func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
        UsageAnalytics.shared.didRegisterForRemoteNotificationsWithDeviceToken(deviceToken: deviceToken)
    }

func application(_ application: UIApplication, didFailToRegisterForRemoteNotificationsWithError error: Error) {
    UsageAnalytics.shared.didFailToRegisterForRemoteNotificationsWithError(error: error)
}

Enabling Loyalty Index for Android

To enable Loyalty Index for your android app you need to register for Firebase Cloud Messaging and then submit your app's FCM key (available as Server Key in your Firebase console.).

A detailed guide about registering your app for FCM can be found here: external link.

Then change your Notification Receiver service class (with intent filter com.google.firebase.MESSAGING_EVENT) as follows,

public class MyFirebaseNotificationService extends FirebaseMessagingService {
    @Override
    public void onNewToken(String s) {
        super.onNewToken(s);
        UsageAnalytics.updateDeviceToken(s);
        // Handle token if you are implementing FCM in your app.
    }
    // Rest of your code
}

Enabling Loyalty Index for Hybrid - Cordova/PhoneGap/Ionic

The pushNotificationDeviceToken will be the deviceToken obtained while using any push notification providers. This value can be obtained during push notification registration of the provider.

cordova.plugins.SmartKarrot.registerNotificationWithToken(“pushNotificationDeviceToken”, successCallback(), failureCallback())

If the app fails to register for push Notification, use the below code

cordova.plugins.SmartKarrot.failRegisterNotificationWithError(“error”, successCallback(), failureCallback())

No code is required to configure Loyalty Index for Android.

Feedback Index

Feedback Index is a measure of your app's rating across iOS App Store & Google Playstore.

Enabling for iOS

iOS App Store ratings are publicly available. So, you don't need to do anything.

Enabling for Android App:

For Android, you need to authorize the SmartKarrot platform to fetch your app's rating on your behalf. For this, you need to generate a service account with view access and submit the credentials json file while onboarding. Here is step by step guide to help you service account credentials file: Generating Service Account