Skip to content

API Documentation And Code Snippets

Index

Analytics Plugin

streethawkinit

Use streethawkinit to initialise streetHawk in your application. Add your application’s app_key registered with streetHawk servers as function argument.

<script type="text/javascript" src="plugins/com.streethawk.core/www/Streethawk.js"></script>
...
...
document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
    var sh = cordova.require("com.streethawk.core.Streethawk");
    sh.shSetGcmSenderId("<SenderID>");
    sh.shSetiTunesId('<Itunesid>');
    sh.streethawkinit();
}
setAppKey

Use setAppKey to set your application's app_key from inside the code. Note that the API wont be effective if you are setting app_key in the command used for integrating StreetHawk plugin. Below mentioned are steps to use setAppKey.

var sh = cordova.require("com.streethawk.core.Streethawk");
sh.setAppKey(<APP_KEY>)
tagCuid

Use tagCuid to tag install with a unique identifier

var sh = cordova.require("com.streethawk.core.Streethawk");
sh.tagCuid("<USER_UNIQUE_ID>");
tagUserLanguage

Use tagUserLanguage to tag install with language. When SDK running it automatically tag device's language. Customer can also use this API to tag language.

var sh = cordova.require("com.streethawk.core.Streethawk");
sh.tagUserLanguage("<language>");
tagNumeric

Use tagNumeric to send tag and numeric value associated with it to StreetHawk server. Function tagNumeric takes key and value as function arguments. Sample usage is as shown below.

var sh = cordova.require("com.streethawk.core.Streethawk");
sh.tagNumeric("BidValue",549.99);
tagString

Use tagString to send tag and string value associated with it to StreetHawk server. Function tagString takes key and value as function arguments. Sample usage is as shown below.

var sh = cordova.require("com.streethawk.core.Streethawk");
sh.tagString("productOffer", "Liked");

Also keys can be one of the pre-defined StreetHawk keys which are listed at the end of this document. Sample code using pre-defined StreetHawk keys. Below example demonstrates tagging user’s email address a customer unique id(cuid) .

var sh = cordova.require("com.streethawk.core.Streethawk");
sh.tagString("sh_cuid", "hello@streethawk.com");
tagDatetime

Use tagDatetime to send tag and dateTime value in UTC to StreetHawk server. Function tagDatetime takes key and dateTime value. Sample usage is as shown below.

var sh = cordova.require("com.streethawk.core.Streethawk");
sh.tagDatetime("Birthday", "2014-07-25 15:33:20");

Sample code using pre-defined StreetHawk keys (sh_registered) is as shown below.

var sh = cordova.require("com.streethawk.core.Streethawk");
sh.tagDatetime("sh_registered", "2014-07-25 15:33:20");
incrementTag

Use incrementTag to increment a tag by one. Function incrementTag takes key to be incremented. Sample usage is as shown below.

var sh = cordova.require("com.streethawk.core.Streethawk");
sh.incrementTag("PageVisited");
incrementTagWithValue

Use incrementTagWithValue to increment a tag by the value. Function incrementTagWithValue takes key and value to be incremented. Sample usage is as shown below.

var sh = cordova.require("com.streethawk.core.Streethawk");
sh.incrementTag("PageVisited", 100);
removeTag

Use removeTag to remove a tag. Function removeTag takes key to be removed. Sample usage is as shown below.

var sh = cordova.require("com.streethawk.core.Streethawk");
sh.removeTag("UserDeleted");
setAdvertisementId

Use SetAdvertisementId to provide IDFA (iOS) or advertising id (Android) to StreetHawk SDK.

var sh = cordova.require("com.streethawk.core.Streethawk");
sh.setAdvertisementId("IDFA/advertising_id");
notifyViewEnter

Use notifyViewEnter to notify when user enters a page. Call notifyViewEnter preferably in device ready of all the views of your app or from those views whose analytics you are interested in. Sample usage is as shown below. notifyViewEnter is called to notify StreetHawk server about user entering settings page.

var sh = cordova.require("com.streethawk.core.Streethawk");
sh.notifyViewEnter("<PAGE_NAME>");
notifyViewExit

Use notifyViewExit to notify when user exit a page. Call notifyViewExit preferably in device ready of all the views of your app or from those views whose analytics you are interested in. Sample usage is as shown below. notifyViewExit is called to notify StreetHawk server about user entering settings page.

var sh = cordova.require("com.streethawk.core.Streethawk");
sh.notifyViewExit("<PAGE_NAME>");
getSHLibraryVersion

getSHLibraryVersion returns version of StreetHawk library integrated with your application. Sample usage is as shown below.

var sh = cordova.require("com.streethawk.core.Streethawk");
var sdkVersion;
sh.getSHLibraryVersion(function(result){sdkVersion = result;}, function(error){});
getInstallId

Use getInstallId to fetch StreetHawk assigned installid of the given install

var sh = cordova.require("com.streethawk.core.Streethawk");
var installId;
sh. getInstallId(function(result){installId = result;}, function(error){});
registerInstallEventCallback

Use registerInstallEventCallback callback to let customer know when an install register successfully. The callback contains install id.

var sh = cordova.require("com.streethawk.core.Streethawk");
var installId;
sh.registerInstallEventCallback(function(result){installId = result;}, function(error){});
getCurrentFormattedDateTime

getCurrentFormattedDateTime returns current device time in UTC. sample usage is as shown below.

var sh = cordova.require("com.streethawk.core.Streethawk");
var currentTimeInUTC;
sh.getCurrentFormattedDateTime(function(result){currentTimeInUTC = result;}, function(error){});
getFormattedDateTime

getFormattedDateTime returns StreetHawk format datetime since the miliseconds from 1970 in UTC. sample usage is as shown below.

var sh = cordova.require("com.streethawk.core.Streethawk");
var timeInUTC;
sh.getFormattedDateTime(60*60*1000, function(result){timeInUTC = result;}, function(error){});
shGetAppKey

Use shGetAppKey for fetching app_key your app uses to communicate with StreetHawk server.

var sh = cordova.require("com.streethawk.core.Streethawk");
var appkey;
sh.shGetAppKey(function(result){appkey = result;}, function(error){});
shDeeplinking

If the application is launched using a deeplink URL, shDeepliking returns that deeplink URL back to application for it to parse and launch the page suggested by the URL. shDeeplink return null is the app is not launched using a deeplink URL.

var sh = cordova.require("com.streethawk.core.Streethawk");
var url;
sh.shDeepLinking(function(result){url = result;}, function(error){});
shSendSimpleFeedback

Use shSendSimpleFeedback let app user send feedback for your application to StreetHawk. shSendSimpleFeedback takes title and message for feedback. Sample usage is as shown below.

var sh = cordova.require("com.streethawk.core.Streethawk");
var title = "Congrats";
var message = "Loved your new design";
sh.shSendSimpleFeedback(title, message);
shSetEnableLogs

Use shSetEnableLogs with true as argument to enable logs in StreetHawk Library for debugging purposes. By default logs are disabled in StreetHawk library.Call shSetEnableLogs before calling streethawkinit. Sample usage is as shown below.

var sh = cordova.require("com.streethawk.core.Streethawk");
sh.shSetEnableLogs(true);
shSetiTunesId (iOS only)

Use shSetiTunesId to set iTunes ID of your application. The API call is required for successfully running Rate and Update campaigns. You can chose to ignore the API if you are unaware of the call and later set the iTunes ID for StreetHawk console. The API is iOS specific and Android applications will ignore this call.

var sh = cordova.require("com.streethawk.core.Streethawk");
sh.shSetEnableLogs(true);

Growth Plugin

originateShareWithCampaign

StreetHawk Growth feature lets your user share your application with friends. Also the feature can be extended to invite the new user to a deeplinking page inside your application. Create a Share button inside your application and call originateShareWithCampaign to generate the share url. App can fetch this generated url and share by any medium ie (email, post on Facebook etc). A scheme for deep linking is required for StreetHawk growth.

var sh = cordova.require("com.streethawk.core.Streethawk");
function success(result) {
     var url = result;  Universal unique url for sharing 
     alert(url);
}        
sh.originateShareWithCampaign(utm_campaign, utm_source, utm_medium, utm_content, utm_term, deeplinkUrl, default_url, success, function(){}); 
Parameter Type Description
utm_campaign string ID for the campaign. (Optional parameter)
utm_source string Source by which url will be shared For example email, facebook, twitter, whatsapp etc (Optional parameter)
utm_medium string Medium using which url will be shared. For example cost per click (cpc) (Optional parameter)
utm_content string Content of campaign. (Optional parameter)
utm_term string keywords for campaign. (Optional paramater)
deeplinkUrl string Deeplink URL if you wish to route your new user to a page in your application. (Optional Parameter)
default_url string Fallback url if the shared url is launched from a non supported platform such as desktop (Optional Parameter)
originateShareWithSourceSelection

Alternatively to automate the process of presenting user with share source and detecting utm_source at run time , use originateShareWithSourceSelection() API as shown below.

var sh = cordova.require("com.streethawk.plugin.Streethawk");
sh.originateShareWithSourceSelection(utm_campaign, deeplinkUrl, default_url);
Parameter Type Description
utm_campaign string ID for the campaign. (Optional parameter)
deeplinkUrl string Deeplink URL if you wish to route your new user to a page in your application. (Optional Parameter)
default_url string Fallback url if the shared url is launched from a non supported platform such as desktop (Optional Parameter)

Push Plugin

shSetAlertSetting

shSetAlertSetting lets your user to pause getting push messages for certain duration of time. Application user might find this feature handy in situations such as meeting where he may not desire to receive push messages. The service resumes after the time out.Function shAlertSetting takes minutes to be paused. A maximum pause time of 129600 minutes(3 months) is permitted beyond which pause is considered as for ever. Sample usage for pausing push messages for one hour is as shown below.

var sh = cordova.require("com.streethawk.core.Streethawk");
var pauseMinutes = 60;
sh.shSetAlertSetting(pauseMinutes);
shGetAlertSettings

Use shGetAlertSettingsto query time remaining to enable push messages again for the user. shGetAlertSettingscan be used as shown below.

var sh = cordova.require("com.streethawk.core.Streethawk");
var remainingTime;
sh.shGetAlertSettings(function(result){remainingTime = result;}, function(error){});
shSetGcmSenderId (Android only)

Use shSetGcmSenderId to set the sender id required for configuring push notifications for your application to run on Android devices. Please refer to Configure Push Messaging (Android) for steps to obtain a SenderID. Note that the call will be ignored in case od

var sh = cordova.require("com.streethawk.core.Streethawk");
sh.shSetGcmSenderId("<SenderID>");
pushDataCallback

Use pushDataCallback to receive push data from StreetHawk server in your application. Refer to table 1 for pushdata variables and table 2 for action codes.

var sh = cordova.require("com.streethawk.core.Streethawk");
function shSuccess(result){
var action = result.action;
var title = result.title;
var message =result.message;
var msgid = result.msgid;
var data    = result.data;
var portion = result.portion;
var orientation = result.orientation;
var speed   = result.speed;
var sound   = result.sound;
var badge   = result.badge;
var noDialog    = result.displaywihtoutdialog;
sh.pushDataCallback(shSuccess,function(){}); // registering call back again
}
sh.pushDataCallback(shSuccess,function(){});
pushResultCallback

Use pushResultCallback to receive push result from StreetHawk server in your application.Refer to table 1 for pushdata variables, table 2 for action codes and table 3 for push result codes.

var sh = cordova.require("com.streethawk.core.Streethawk");
function shSuccess(result){
var pushResult  = result.result
var action = result.action;
var title = result.title;
var message =result.message;
var msgid = result.msgid;
var data    = result.data;
var portion = result.portion;
var orientation = result.orientation;
var speed   = result.speed;
var sound   = result.sound;
var badge   = result.badge;
var noDialog    = result.displaywihtoutdialog;
sh.pushResultCallback(shSuccess,function(){}); // registering call back again
}
sh.pushResultCallback(shSuccess,function(){});
shRawJsonCallback

Use shRawJsonCallback function to receive JSON from StreetHawk server and implement the expected functionality based on it in the application.

var sh = cordova.require("com.streethawk.core.Streethawk");
function shSuccess(result){
        var title = result.title;
        var message  = result.message;
        var rawjson = result.json;
        sh.shRawJsonCallback(shSuccess,function(){}); // registering call back again
    }

sh.shRawJsonCallback(shSuccess,function(){});
shRegisterViewCallback

Use shRegisterViewCallback to query name of the API which StreetHawk library received from console when the app is in foreground. Preferably call this api just after streethawkinit().

var sh = cordova.require("com.streethawk.core.Streethawk");
var viewName;
sh.shRegisterViewCallback(function(result){viewName = result;}, function(error){});
shGetViewName

Use shGetViewName to query name of the API which StreetHawk library received from console when the app is in background.

var sh = cordova.require("com.streethawk.core.Streethawk");
var viewName;
sh.shGetViewNames(function(result){viewName= result;}, function(error){});
setUseCustomDialog (Android only)

Use setUseCustomDialog to true if you wish to handle StreetHawk push messages in dialogs customised for your application

var sh = cordova.require("com.streethawk.core.Streethawk");
sh.setUseCustomDialog(true)
sendPushResult

use sendPushResult to send push result to StreetHawk SDK. The API can be used to notify push result if you are handling pushData using your custom dialog

var sh = cordova.require("com.streethawk.core.Streethawk");
sh.sendPushResult(pushData.msgId,1);
registerNonSHPushPayloadObserver

use registerNonSHPushPayloadObserver to let customer know callback when a none StreetHawk push received.

var sh = cordova.require("com.streethawk.core.Streethawk");
sh.registerNonSHPushPayloadObserver(function(result){alert("none StreetHawk payload callback: " + JSON.stringify(result))}, failCallback);
addInteractivePushButtonPairWithIcons,
addInteractivePushButtonPair and
setInteractivePushBtnPair

use addInteractivePushButtonPairWithIcons, addInteractivePushButtonPair and setInteractivePushBtnPair to set interactive button pairs. The sample code as below:

var sh = cordova.require("com.streethawk.core.Streethawk");
sh.addInteractivePushButtonPairWithIcons("Facebook", "", "Twitter", "", "Social");
sh.addInteractivePushButtonPairWithIcons("Invite", "", "Test", "", "InviteTest");
sh.addInteractivePushButtonPair("agree", "disagree", "Agree_Disagree");
sh.setInteractivePushBtnPair();
forcePushToNotificationBar (Android only)

For your application running in foreground, use forcePushToNotificationBar is you want to force notification to be displayed in notification bar so as to prevent user from being distracted by alert dialog.(for example, in case of gaming application you may not want to distract user with an alert dialog when he is in middle of a gaming session).

var sh = cordova.require("com.streethawk.core.Streethawk");
sh.forcePushToNotificationBar();

you can reset the API call by passing false as argument.

  • Table 1: PushData variables and description
Variable Description
action Action associated to push msg. Action codes are listed in table below
msgid Id of push notification
title Title associated to a push message
message Message associated to a push message
data Data associated to a push message. Refer to table 4 for more details
portion If action = ACTION_OPEN_URL, portion denotes percentage of screen covered by animated webview which will display url in app.
orientation If action = ACTION_OPEN_URL, portion denotes direction from which the animated dialog will pop out.
speed If action = ACTION_OPEN_URL, speed denotes time in seconds for which the slide animation will be rendering.
displaywithoutdialog If action = ACTION_OPEN_URL,displaywithoutdialog if true, will display animated webview without confirmation dialog to user
sound File name of sound file which needs to be played as notification sound
badge Number to be displayed as badge. Not all Android devices can display badge
result Displays push result. Click here for push results
  • Table 2: Actions and respective codes
Action Code
ACTION_OPEN_URL 1
ACTION_LAUNCH_ACTIVITY 2
ACTION_RATE_APP 3
ACTION_USER_REGISTRATION_SCREEN 4
ACTION_USER_LOGIN_SCREEN 5
ACTION_UPDATE_APP 6
ACTION_CALL_TELEPHONE_NUMBER 7
ACTION_SIMPLE_PROMPT 8
ACTION_FEEDBACK 9
ACTION_ENABLE_BLUETOOTH 10
ACTION_ENABLE_PUSH_MSG 11
ACTION_ENABLE_LOCATION 12
  • Table 3 Push results codes and value
Push result Value
ACCEPTED 1
POSTPONED 0
DECLINE -1
  • Table 4 Data associated to actions
Action Data
ACTION_OPEN_URL Web url
ACTION_LAUNCH_ACTIVITY App page to be displayed
ACTION_RATE_APP NULL
ACTION_USER_REGISTRATION_SCREEN App page to be displayed
ACTION_USER_LOGIN_SCREEN App page to be displayed
ACTION_UPDATE_APP NULL
ACTION_CALL_TELEPHONE_NUMBER Phone number to be called
ACTION_SIMPLE_PROMPT NULL
ACTION_FEEDBACK JSON with feedback options. Empty JSON object for displaying simple feedback dialog
ACTION_ENABLE_BLUETOOTH NULL
ACTION_ENABLE_PUSH_MSG NULL
ACTION_ENABLE_LOCATION NULL

Geofence Plugin

startGeofenceMonitoring (Android only)

Android Use startGeofenceMonitoring to enable application to detect a geofence registered with StreetHawk. The call is mandatory as starting API 23 (Android Marshmallow) user is prompted for location permission to enable locations to be reported by application. API is ignored for version less than API23 where locations reporting is automatically enabled.

var sh = cordova.require("com.streethawk.core.Streethawk");
sh.startGeofenceMonitoring();
stopGeofenceMonitoring (Android only)

Use stopGeofenceMonitoring to disable application to detect a geofence registered with StreetHawk.

var sh = cordova.require("com.streethawk.core.Streethawk");
sh.stopGeofenceMonitoring();
startGeofenceWithPermissionDialog (Android only)

Android Use StartGeofenceWithPermissionDialog to present user with a permission dialog and enable application to detect a geofence registered with StreetHawk if user responds to it with a positive action. The call is mandatory as starting API 23 (Android Marshmallow) user is prompted for location permission to enable locations to be reported by application. API is ignored for version less than API23 where locations reporting is automatically enabled.

var sh = cordova.require("com.streethawk.core.Streethawk");
var message = "Get great deals as soon as you enter our shop";

sh.StartGeofenceWithPermissionDialog(message);
setNotifyGeofenceEventCallback

Use setNotifyGeofenceEventCallback callback when enter or exit a geofence region.

var sh = cordova.require("com.streethawk.core.Streethawk");
sh.setNotifyGeofenceEventCallback(function(result){alert("geofence enter/exit callback: " + JSON.stringify(result))}, failCallback);

Location Plugin

startLocationReporting (Android only)

Android Use startLocationReporting to enable reporting of user's location to StreetHawk. The call is mandatory as starting API 23 (Android Marshmallow) user is prompted for location permission to enable locations to be reported by application. API is ignored for version less than API 23 where locations reporting is automatically enabled.

var sh = cordova.require("com.streethawk.core.Streethawk");
sh.startLocationReporting();
stopLocationReporting (Android only)

Use stopLocationReporting to disable application to detect a geofence registered with StreetHawk.

var sh = cordova.require("com.streethawk.core.Streethawk");
sh.stopLocationReporting();
reportWorkHomeLocationOnly

Use reportWorkHomeLocationsOnly() API if you wish to use location module only to calculate Work and Home locations of your user. Please note that with this approach, you wont be able to run location based campaigns. Following is a code snippet to demonstrate use of reportWorkHomeLocationsOnly(). You need not call this API if you are already using startLocationReporting().

var sh = cordova.require("com.streethawk.core.Streethawk");
sh.reportWorkHomeLocationOnly();
updateLocationMonitoringParams

Use updateLocationMonitoringParams for changing minimum distance and interval for location reporting. The default parameters are

Application State Distance in meters Interval in minutes
Foreground 100 2
Background 500 6
var sh = cordova.require("com.streethawk.core.Streethawk");
var fg_interval = 2;         // 2 minutes
var fg_distance = 100;   // 100 meters
var bg_interval = 6;        // 6 minutes
var bg_distance = 500;  // 500 meters

sh.updateLocationMonitoringParams(fg_interval,fg_distance,bg_interval,bg_distance);
startLocationWithPermissionDialog (Android only)

Android Use startLocationWithPermissionDialog to present user with a permission dialog and enable application to detect a geofence registered with StreetHawk if user responds to it with a positive action. The call is mandatory as starting API 23 (Android Marshmallow) user is prompted for location permission to enable locations to be reported by application. API is ignored for version less than API23 where locations reporting is automatically enabled.

var sh = cordova.require("com.streethawk.core.Streethawk");
var message = "Get great deals as soon as you enter our shop";

sh.startLocationWithPermissionDialog(message);

Feeds Plugin

notifyNewFeedCallback

Implement notifyNewFeedCallback to be informed when a new feed item is available for download from StreetHawk server.

var sh = cordova.require("com.streethawk.core.Streethawk");

function newFeed(result){

}
sh.shRegisterViewCallback(newFeed, function(error){});
reportFeedAck

Use reportFeedAck to acknowledge feed item received by StreetHawk server.

var sh = cordova.require("com.streethawk.core.Streethawk");
var feedid=2;
sh.reportFeedAck(feedid);
reportFeedRead

Use reportFeedRead to send user's action to feed item.

var sh = cordova.require("com.streethawk.core.Streethawk");
var feedid=2;
var feedResult = 1;
sh.reportFeedRead(feedid,feedresult);
shGetFeedDataFromServer

Use shGetFeedDataFromServer to fetch feed data from StreetHawk server.

var sh = cordova.require("com.streethawk.core.Streethawk");
var offset = 0;
function newFeed(result){
offset = offset+20;
}
sh.shRegisterViewCallback(newFeed, function(error){});
sh.getFeedDataFromServer(offset);

Delay asking for iOS notification permission (iOS only)

By default StreetHawk library register push notification on initialisation. In case you may wish to delay this and ask the user for push notification permission at the right time, you can use shSetDefaultNotificationService as shown below.

var sh = cordova.require("com.streethawk.core.Streethawk");
sh.shSetDefaultNotificationService(false); //make streethawkinit not register for user notification, delay for later time.
//do streethawkinit and other things.
sh.shSetNotificationEnabled(true);  //later when ready to register for user notification, call this.

At any time, you can check whether notification is enabled by code:

var sh = cordova.require("com.streethawk.core.Streethawk");        
function failCallback(result) {
      alert("Fail: " + result);
}
var isNotificationEnabled;
sh.shGetNotificationEnabled(function(result){isNotificationEnabled = result;}, failCallback);

Delay asking for iOS location permission (iOS only)

Include in streethawklocations plugin, or streethawkgeofence plugin.

By default StreetHawk library request for location permission as soon as streethawkinit is called. In case you wish to delay this and later ask the user for location permission at an appropriate time, you can add the code be as shown below.

var sh = cordova.require("com.streethawk.core.Streethawk");
sh.shSetDefaultLocationService(false); //make streethawkinit not enable location service, delay for later time.
//do streethawkinit and other things.
sh.shSetLocationEnabled(true);  //later when ready to enable location service, call this.

At any time, you can check whether location is enabled by code:

var sh = cordova.require("com.streethawk.core.Streethawk");
function failCallback(result) {
    alert("Fail: " + result);
}
var isLocationEnabled;
sh.shGetLocationEnabled(function(result){isLocationEnabled = result;}, failCallback);