API Documentation And Code Snippets¶

Index¶

Analytics Plugin
Growth Plugin
- originateShareWithCampaign
- originateShareWithSourceSelection
Push Plugin
Geofence Plugin
Location Plugin
Feeds Plugin

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);