Developer

  1. Introduction
  2. Web Administrator
    1. Analytics
      1. Dash
      2. Live
        1. Live Feeds
        2. Recent Engagements
        3. Real Time Monitor
        4. Monthly Active Users
        5. Content Click Through Rate
      3. Triggers
        1. Traffic
        2. Recent Interactions
        3. Popular Touch
      4. Devices
        1. Device
        2. Device Click Through Rate
        3. Device History
      5. Reports
        1. On-Demand Reports
        2. Saved Reports
        3. Notifications
    2. Campaigns
      1. Calendar
      2. Events
        1. Managing Your Events
        2. Basic Info
        3. Scheduling
        4. Conditions
        5. Deleting Events
        6. Duplicating Events
        7. Variables
        8. Action
        9. Notification
        10. Recent Interactions
        11. Event Click Through Rate
        12. Traffic
    3. Content
      1. Touch/Scan Actions
        1. Landing Pages
        2. Custom Actions
      2. Landing Page Branding
        1. Interstitial Preview
      3. Interstitials
        1. Adding a New Interstitial with the WYSIWYG Editor
          1. Interstitial Info
          2. Your Files
        2. Adding a New Interstitial with the Code Editor
          1. Interstitial Info
          2. Your Files
          3. Web Page
    4. Deployment
      1. Groups
        1. Managing Your Groups
        2. Adding or Editing Groups
        3. Action Details
        4. Events
        5. Beacons
        6. Geofences
        7. Wi-Fi Networks
        8. Recent Interactions
        9. Platforms
        10. Browsers
        11. Popular Touch
        12. Traffic
        13. Calendar
        14. Recent Engagements
        15. Map
        16. Delete Groups
      2. Geofences
        1. Managing Your Geofences
        2. Adding or Editing a Geofence
        3. Location Widget
        4. Variables
        5. Recent Transitions
        6. Traffic
        7. Calendar
        8. Deleting Geofences
        9. Adding Multiple Geofences Using Bulk Upload
      3. Beacons
        1. Managing Your Beacons
        2. Unique Beacon Identifiers
        3. Adding or Editing Beacons
        4. Variables
        5. Recent Interactions
        6. Traffic
        7. Event
        8. Deleting Beacons
        9. Adding Multiple Beacons Using Bulk Upload
      4. Wi-Fi
        1. Managing Wi-Fi Networks
        2. Adding or Editing Wi-Fi Networks
        3. Variables
        4. Recent Transitions
        5. Traffic
        6. Events
        7. Deleting a Wi-Fi Network
        8. Adding Multiple Wi-Fi Networks Using Bulk Upload
      5. Touch/Scan Triggers
        1. Managing Your Tags
        2. Export Tags
        3. Bulk Operations
        4. Editing Tag Settings
        5. Action
        6. Recent Engagements
        7. Info
        8. Variables
        9. Traffic
      6. Trigger Map
    5. Admin
      1. Manage Users
        1. Adding New Users
        2. Edit User
        3. Roles
        4. Permissions
        5. Deleting Users
      2. Audit Trail
      3. Account Information
        1. Edit Account
        2. Account Information
        3. Developer Information
        4. Customer Database
      4. File Manager
      5. Application IDs
        1. Adding or Editing Application IDs
        2. Deleting Application IDs
  3. Android Client SDK Integration Guide
    1. Release Notes
    2. Requirements
    3. Project Configuration for Android Studio
    4. Client Integration
    5. Proximity Notifications
    6. Actions
    7. Attributes and Event Conditions
    8. Interstitials
    9. Project Configuration for Eclipse
  4. iOS Client SDK Integration Guide
    1. Release Notes
    2. Requirements
    3. Project Configuration
    4. Client Integration
    5. Actions
    6. Proximity Notifications
    7. Attributes and Event Conditions
    8. Interstitials
  5. Smartwhere on GitHub
  6. Login to the Web Administrator

Introduction

Welcome to the Smartwhere Developer Portal

This portal is your hub for SDK integration documentation, walkthroughs on managing your campaigns and proximity technologies through the Web Administrator, as well as links to sample applications.

To get started with an account, please contact us at info@smartwhere.com.  For help with the documentation, please contact us at support@smartwhere.com.

Web Administrator

  • For information on reviewing your proximity campaign performance see the Analytics tab in the Web Administrator
  • For information on scheduling your proximity campaigns, see the Campaigns tab in the Web Administrator
  • For information on creating content and managing actions triggered by your proximity campaigns see the Content tab in the Web Administrator
  • For information on managing your network of proximity technologies see the Deployment tab in the Web Administrator
  • For information on managing your account, including user access and app account info see the Admin tab in the Web Administrator

SDK Integration

Smartwhere on Github

To obtain demo sample applications, for both Android and iOS, please visit our Github page.

Login to the Web Administrator

Click this link to log directly into the Smartwhere Web Administrator using your own user name and password.


Smartwhere © 2013-2016, Android and iOS and other trademarks are the properties of their respective trademark holders.

Yes No Suggest edit
Last updated on February 5, 2016

Web Administrator

The Smartwhere Web Administrator is the central location for managing your proximity campaigns for your mobile apps and managing the Smartwhere platform as a whole. From this web tool you can review current performance of your campaigns in detail via the Analytics tab. Schedule your campaigns and the associated proximity triggers from the Campaigns tab. Create and manage the actions and content triggered by your proximity technologies from the Content tab. Configure and manage your proximity technologies from the Deployment tab. Finally, manage your platform users and apps from the Admin tab.


Yes No Suggest edit
Last updated on February 17, 2016

Analytics Overview

The Analytics tab displays transitions and engagement with your Proximity Technologies. It provides information on performance, recent interactions and metrics.


Yes No Suggest edit
Last updated on February 2, 2016

Dash

The Dash is a customizable page. Each user can customize content on the Dash by pinning widgets that they use or access most often. Pinnable widgets are represented by a Pin in the header area. Simply click the Pin, and you will see a confirmation that the widget has been pinned successfully.

To access the Dash, click into the Analytics tab, and then Dash in the sidebar.  

The first time you access the Dash, it will be blank:

01-dash

You can choose to leave this page blank, or pin any of the following widgets:

Analytics

Live: All widgets in this section can be pinned

Traffic: Recent Interactions,Popular Touch

Devices: Devices

Reports: Saved Reports, Notifications

Campaigns

Calendar: Calendar

Events: Event

Deployment

Groups: All widgets can be pinned

Wireless Triggers: All widgets can be pinned

Touch/Scan Trigger: All widgets can be pinned

Users can pin as many widgets as needed to the Dash.

To pin tables or widgets to the Dashboard, click the Pin button in the Widget Heading Bar.   pinned

A table or widget that has successfully been pinned will appear like this: unpinned

To unpin, re-click the Pin button. 


Yes No Suggest edit
Last updated on February 11, 2016

Live

 

The Live section provides real-time feedback on the current performance of your system.


Yes No Suggest edit
Last updated on February 15, 2016

Live Feeds

The Live Feeds widget displays the transitions generated by each of the Proximity Technologies. It shows all transactions, then refreshes to show new transitions registered on a per second interval.

01-livefeeds

To pin this table to the Dashboard, click the Pin button in the Widget Heading Bar. pinned

A table or widget that has successfully been pinned will appear like this: unpinned

To unpin, re-click the Pin button. 

Yes No Suggest edit
Last updated on February 17, 2016

Recent Engagements

The Recent Engagements widget displays recent traffic events for each of the Proximity Technologies. The table shows the ten most recent engagements, reporting the Action, Device ID, Platform and the Timestamp of the occurrence. The timestamp displayed corresponds to the time zone of the account owner (see the Timezone setting under Account Info for the account-level setting).    

02-recentengagements
To pin this table to the Dashboard, click the Pin button in the Widget Heading Bar.  pinned

A table or widget that has successfully been pinned will appear like this: unpinned

To unpin, re-click the Pin button. 

Clicking on the device ID opens an expanded view for that device. In the expanded view, information pertaining to the device is displayed, such as the SDK version installed, the device click-through-rate, and the device history. For more information, please see the Devices section.

03-deviceid

Yes No Suggest edit
Last updated on February 18, 2016

Real Time Monitor

The Real Time Monitor widget displays the location of recent Traffic and Events. Each location pin represents a traffic record, and is dropped on the map when a notification fires on an end user’s device. You can zoom in and out on the map using the control in the lower right-hand corner of the map, and reposition the map by clicking and dragging the cursor.

04-realtimemonitor

To pin this table to the Dashboard, click the Pin button in the Widget Heading Bar.  pinned

A table or widget that has successfully been pinned will appear like this: unpinned

To unpin, re-click the Pin button. 

Yes No Suggest edit
Last updated on February 17, 2016

Monthly Active Users

The Monthly Active Users widget displays the number of unique users who have interacted at least once in a given month with one of your Proximity Technologies. Interaction in this widget refers to an Enter action for Wireless Triggers (Geofences, Wifi Networks, Beacons) or Touch/Scans for NFC tags or QR codes.

05-mau

To pin this table to the Dashboard, click the Pin button in the Widget Heading Bar.  pinned

A table or widget that has successfully been pinned will appear like this: unpinned

To unpin, re-click the Pin button.

Yes No Suggest edit
Last updated on February 17, 2016

Content Click Through Rate

The Content Click Through Rate widget shows the Impressions and Clicks recorded. A notification firing on a device will register as an Impression, while a click on the notification on the device will register as a Click.

In order for the Impression and Click to register, a Category must be selected on the Event. If the Event does not have a Category assigned, the Click Through Rate data will not be available. The data in this widget is a total of all Events with a Category and all devices.

04a-contentctr

Within the widget, you can search for categories using the search box, sort by clicking the column headings, or change the number of entries displayed using the drop-down in the upper right-hand corner. If the number of entries in the widget is greater than the number of entries displayed, you can use the Previous and Next buttons to move between pages.

Yes No Suggest edit
Last updated on February 17, 2016

Triggers

The Triggers section provides information about the performance of the various proximity triggers available to the system.


Yes No Suggest edit
Last updated on February 15, 2016

Traffic

The Traffic widget lists all transitions (e.g, Geofence Enter, Geofence Dwell, etc). From this table, you can sort and filter on device ID, Source (or Transition type), Platform, Version (referring to the device’s OS version), and Age (the number of days since the traffic record was created). You can also search within the columns using the search box at the top of the table.

01-traffic

 

The columns in this table can be sorted by clicking on the headers. Each header also includes a searchable text field to filter for specific items.  

In the upper left, you can change the number of entries displayed.  If you have more Tag IDs than number of entries displayed, you can use the Previous and Next buttons in the lower right to navigate in between pages.

To drill down into a specific device, click on the Device Id. Please see the Device section for more.

Yes No Suggest edit
Last updated on February 19, 2016

Recent Interactions

The Recent Interactions widget provides additional metrics, using date or time as a lens to review performance data.

02-recentinteractions

To pin this table to the Dashboard, click the Pin button in the Widget Heading Bar.  pinned

A table or widget that has successfully been pinned will appear like this: unpinned

To unpin, re-click the Pin button.

Within the widget, use the Reporting Period drop-down to choose from the following. These selections are applicable for each of the tabs:

  • Date: Performance by date
  • Hour: Performance by the hours in a day
  • Day of week: Performance by the day of week (Monday – Sunday)

Filter your results for a specific time period using the Date Range fields. Date format is YYYY-MM-DD (time is optional, if you wish to add time as a filter, the format is HH:MM:SS).

The tabs within the widget show different filtered views for the Recent Interactions.

TIP: The data on each tab is filtered by the date range or Reporting Period drop-down at the top of the widget.

  • The Summary tab displays an all-up view. You can view transition information against each of your Proximity Technologies, your clicks vs impressions sent, and the number of installs on Android and iOS devices.

03-summary

  • The Transition tab displays the transitions by Proximity Technology by date.

04-transitions

  • The Engagements tab displays Impressions and Clicks by date.

05-engagements

  • The Installations tab displays the Installations by platform by date.

06-installations

Yes No Suggest edit
Last updated on February 17, 2016

Devices

The Devices section displays information about end user devices:

ID: This is a device identification code issued by Smartwhere for the device.  

Device: This is the model type of the device.

Mobile: “Yes” indicates that the device is a mobile device (phone, tablet). “No” indicates that the device is a desktop or laptop computer.

Platform: The operating system of the device

Platform Version: The version of the operating system installed on the device

Browser: This column displays  “SDK” for mobile devices with an app installed using the Smartwhere SDK, or it  displays the mobile web browser used for tap/scan actions (e.g. Chrome Mobile) .

Version: The version of the Smartwhere SDK installed on the app, or the version of the web browser used.

01-devices

Navigating the Devices Table

To pin this table to the Dashboard, click the Pin button in the Widget Heading Bar.  pinned

A table or widget that has successfully been pinned will appear like this: unpinned

To unpin, re-click the Pin button.

The columns in this table can be sorted by clicking on the headers.  Each header also includes a searchable text field to filter for specific items.

In the upper left, you can change the number of entries displayed.  If you have more Device IDs than number of entries displayed, you can use the Previous and Next buttons in the lower right to navigate in between pages.

Exporting Table Contents

Clicking the Copy button allows you to copy the table to paste into a different document.

02-copydevices

Clicking the CSV, Excel or PDF buttons allows you to save a document locally as that file type.

03-savedevice

Clicking the Print button provides a Print Preview version of the table. Clicking the “ESC” key will return you to the Administrator.

04-printdevice

Yes No Suggest edit
Last updated on February 19, 2016

Device

Clicking on the Device ID opens an expanded view for that device. The Device widget displays details about the device displayed in the Device table.

05-device

Yes No Suggest edit
Last updated on February 18, 2016

Device Click Through Rate

The next widget is Device Click Through Rate.

In order for Device Click Through Rates to be registered, a Category must have been added during the Event setup. If the Event does not have any categories, the Device Click-Through Ratewill not be available.

Within the table, you can search for categories using the search box, sort by clicking the column headings, or change the number of entries displayed using the drop-down in the upper right-hand corner. If the number of entries in the widget is greater than the number of entries displayed, you can use the Previous and Next buttons to move between pages.

06-deviceCTR

Yes No Suggest edit
Last updated on February 18, 2016

Device History

The Device History widget displays the transition records and history for this device, including when a transition happened (TimeStamp), what happened (Impression or Click), what caused the notification to fire on the device (the transition type), where it happened (the location and latitude/longitude), and the Group associated with the Event.

07-devicehistory

You can search within the columns using the search box, or sort by clicking the column headings.

This table can be expanded to display 10, 25, 50, or 100 entries using the drop-down option in the upper left hand corner of the table. You can export the data via CSV, Excel or PDF. You can also copy or print the entries  in the table.

History Map

The History Map widget displays where transitions occurred for each device. Clicking a location pin on the map provides a closer look at the type of transition.

08-historymap

Yes No Suggest edit
Last updated on February 18, 2016

Reports

The Reports section provides access to pre-generated detailed reports related to the performance of your proximity campaigns.

 

Yes No Suggest edit
Last updated on February 15, 2016

On-Demand Reports

A number of on-demand report options are available from the Reports widget.

01-reports

 

Report types

The Activity Report provides an overall view into your account. It provides a comprehensive and in-depth accounting of usage, transitions and more. It displays metrics such as interactions by hour, interactions by Proximity Technology, Network Providers, Browsers used, etc.

The Beacon Report provides a listing of all Beacons in the account; the IDs, Latitude, Longitude and the Groups to which the Beacons are associated.

The Beacon Traffic Report provides a listing of all notifications triggered against the Beacons on the account.

The Beacon Transition Report provides a listing of all transitions registered against the Beacons on the account.

The Data Usage Report provides the number of unique devices that have interacted with the account, and the number of tags on the account.

The Geofence Traffic Report provides a listing of all notifications triggered against the Geofences on the account.

The Geofence Transition Report provides a listing of all transitions registered against the Geofences on the account.

Tag Export Report provides a listing of all Tags on the account, their IDs, tag creation date, the Group to which the tag is associated, and the number of Taps and Scans registered.

Tag Traffic Report is a comprehensive Tags report that includes information about specific device interactions, including the device type, the platform and platform version, when the interaction occurred, and the resulting action.

The WifiTrafficReport provides a listing of all notifications triggered against the Wi-Fi Networks on the account.

The WifiTransitionReport provides a listing of all transitions registered against the Wi-Fi Networks on the account.

The widgets on this page include search and navigation controls. You can use the text search field to search for a specific report. If you have more than 10 Reports, you can navigate in between pages using the Previous and Next buttons in the lower right, or you can use the drop-down to change the number of rows displayed.

Generate Activity Report

Click on Activity Report in the Report widget to define the report criteria.

04-activityreport

Activity Report fields

Destination Email (Required): The default value is the email address of the account owner, but the report recipient’s address may be changed.  

Output Format: The format for the generated report. Options are:

  • PDF document
  • HTML page

Page Size: Determines the size of the page for the generated report. Options are:

  • A4
  • Letter
  • Legal
  • Executive
  • Folio
  • Demy
  • Royal

Orientation: Determines the layout of the report. Options are:

  • Portrait
  • Landscape

Customer: Displays the name of the account owner.

Group: Select from the drop-down list to filter the report for information regarding a specific Group, or Groups in the account.

Date Start/Date End: Select Date range for the report. This field is optional; if you do not make a selection, the default provides all records. The Date format is MM-DD-YYYY.  Alternatively, you can select the date on the pop-up Calendar that appears by clicking the date text field.

Description: If you would like to save the parameters of this report, you can use this field to provide a description of the report. The description will appear in the Description column in the Saved Reports widget. This field is optional.

Save Report: Click this button to save the parameters entered above. The report will be saved in the Saved Reports widget.

Run Report: Click this button to run the report and send it to the email address specified in the Destination Email field.  

NOTE: A link to the report will appear in the Notification widget once the report has been generated and emailed.

Generate Beacon Report

Click on Beacon Report in the Report Widget.

05-beaconreport

Beacon Report fields

Destination Email (Required): The default value is the email address of the account owner, but you can change the recipient of the report.   

Customer: Displays the name of the account owner.

Group: Select from the drop-down list to filter the report for information regarding a specific group, or all in the account.

Descriptions: If you would like to save the parameters of this report, this field will be displayed in the description column in the  Saved Report widget.

Save Report: Click this button to save the parameters entered above. The report will be saved in the Saved Reports widget.

Run Report: clicking this button will run the report and send via email to the email address specified in the Destination Email field. 

NOTE: A link to the report will appear in the Notification widget once the report has been generated and emailed.

Generate Data Usage Report

Click on Data Usage Report in the Report widget.

06-datausage

Data Usage Report settings

Destination Email (Required):  The default value is the email address of the account owner, but you can change the recipient of the report.  

Customer: Displays the name of the account owner (not editable).

Month: Allows filtering of results by Month and Year.  To customize Month, click on the first set of dashes in the field.  You can type in the month, or use the up/down arrows to the right.  To customize year, you can type in the year, or use the up/down arrows.  This field is not required; leaving this field as the default will show all data usage.

Description: If you would like to save the parameters of this report, this field will be displayed in the description column in the  Saved Report widget.

Save Button: clicking this button will save parameters entered above and save to the Saved Reports widget.

Run Report: clicking this button will run the report and send via email to the email address specified in the Destination Email field.  

NOTE: A link to the report will appear in the Notification widget once the report has been generated and emailed.

Generate Tag Export Report

Click on the Tag Export Report in the Report widget.

07-tagexport

Tag Export Report settings

Destination Email (Required): The default value is the email address of the account owner, but you can change the recipient of the report.  

Customer: Displays the name of the account owner (not editable).

Group: Select from the drop-down to filter the report for information regarding a specific group, or all in the account.

Description: If you would like to save the parameters of this report, this field will be displayed in the description column in the  Saved Report widget.

Save Button: clicking this button will save parameters entered above and save to the Saved Reports widget.

Run Report: clicking this button will run the report and send via email to the email address specified in the Destination Email field.  

NOTE: A link to the report will appear in the Notification widget once the report has been generated and emailed.

Generate Tag Traffic Report

Click on Tag Traffic Report in the Report widget.

08-tagtraffic

Tag Traffic Report settings

Destination Email (Required): The default value is the email address of the account owner, but you can change the recipient of the report.  

Customer Id: Displays the name of the account owner .

Description: If you would like to save the parameters of this report, this field will be displayed in the description column in the Saved Report widget.

Save Button: Clicking this button will save parameters entered above and saved to the Saved Reports widget.

Run Report: Clicking this button will run the report and send via email to the email address specified in the Destination Email field.  

NOTE: A link to the report will appear in the Notification widget once the report has been generated and emailed.

The Traffic and Transition reports request the same information as the other reports listed above.

Yes No Suggest edit
Last updated on February 19, 2016

Saved Reports

02-savedreports

When generating a report, you will have the option of saving the report by clicking the Save Report button. This saves the parameters (such as report recipient, date range of report) on the report request form. Once you save, that report will be listed in the Saved Reports widget.  

You can run a saved report by clicking the Run run button. To edit the saved report’s preferences, such as the date range, click the Edit edit button. To delete the saved report, click the Delete delete button.

Yes No Suggest edit
Last updated on February 18, 2016

Notifications

03-notifications

Notifications widget

When a report is generated, a link to the report is stored in the Notifications widget. This widget lists the generated reports along with the date they were generated. To download the report, click on the hyperlink in the Message column.

Yes No Suggest edit
Last updated on February 18, 2016

Campaigns

The Campaigns tab allows you to create and view your Campaigns. From the sidebar, you can navigate to the following sections:

Calendar: The Calendar displays your scheduled Events on a daily, weekly, and monthly view. This section opens by default on the Campaigns tab.

Events: The Events section allows you to add, edit and delete your Events. You can set triggers, schedules, actions and conditions.


Yes No Suggest edit
Last updated on February 2, 2016

Calendar

The Calendar view opens by default on the Campaigns tab, and displays all of your non-expired events.  

Viewing your Calendar

  1. To view the Calendar, click on the Campaigns tab.
  2. If the Calendar section hasn’t opened, in the left sidebar, click on Calendar.

01-calendar

The Monthly view is the default for the Calendar. To change the view, click the drop-down menu labelled Showing in the Widget’s Heading Bar:

  • Monthly: Displays events for the month.
  • Agenda: Displays 7 days, or a weekly calendar of events.
  • Today: Displays events for a specific day.

To view Events scheduled for a previous time period, use the Back and Forward arrows in the upper-left of the widget.

As you add or edit Events, the changes to the Name, Description, Trigger and Schedule will appear on the Calendar. New Events appear as new items on the Calendar.

Pinning the Calendar widget

The Calendar widget is pinnable to the Dash.

To pin this widget to the Dashboard, click the Pin button in the Widget Heading Bar.  pinned

A table or widget that has successfully been pinned will appear like this: unpinned

To unpin, re-click the Pin button. 


Yes No Suggest edit
Last updated on February 11, 2016

Events

Events are your schedule of Actions, Groups and triggers. It tells the story of what is going to happen (Actions), why (Proximity elements in a Group and the trigger) and when (schedule).

Yes No Suggest edit
Last updated on February 17, 2016

Managing Your Events

  1. To view and manage your Events, click on the Campaigns tab.
  2. In the left sidebar, click on Events.

01-events

The Events table displays any scheduled events.

ID: This is the identifier the system assigns to the Event.  

Title: This is the title of the Event, set by you, or auto-generated by the system when the Event is added.

Description: This is your description of the Event.

Weighting: Displays the weighted value of the Event.

Start: Displays the Event’s start date.

End: Displays the Event’s end date.

Group: The Group your Event is assigned to.

Action: The Action type selected for the Event.

Type: The trigger type selected for the Event.

Navigating the Events Table

To pin this table to the Dashboard, click the Pin button in the Widget Heading Bar. pinned

A table or widget that has successfully been pinned will appear like this: unpinned

To unpin, re-click the Pin button.

The columns in this table can be sorted by clicking on the headers.  Each header also includes a searchable text field to filter for specific items.  

In the upper left, you can change the number of entries displayed.  If you have more Events than number of entries displayed, you can use the Previous and Next buttons in the lower right to navigate in between pages.

Exporting Table Contents

Clicking the Copy button allows you to copy your Events to paste into a different document.

02-tablecopied

Clicking the CSV, Excel or PDF buttons allows you to save a document locally as that file type.

03-saveevents

Clicking the Print button provides a Print Preview version of the table. Clicking the “ESC” key will return you to the Administrator.

04-printview

Yes No Suggest edit
Last updated on February 18, 2016

Basic Info

ADDING OR EDITING AN EVENT

To add a new Event, from the Campaigns tab, click on Events in the sidebar. Create a new Event by clicking theAdd button in the upper right-hand corner of the page. To edit an existing Event, click on the Event name in the table to access its Edit Event widget.

The Edit Event widget includes three tabs: Basic Info, Scheduling, and Conditions.

05-basicinfo
Basic Info settings:

Title (Required): This is the name of the Event. This is what is displayed in the Calendar.

Description (Required): This is a free-text field for a description of the Event.

Offer Interval (Required): This field is the time delay (in minutes) between an event sending a repeating notification. For example, if you have a Geofence Enter Event with an Offer Interval set at 60 minutes, a device will only receive the Geofence Enter notification/action once every 60 minutes, even if the device has entered and exited the Geofence several times within that 60 minutes.

NOTE: As a best practice, consider setting this value high to help prevent end-users from being overwhelmed by notifications. A zero (0) value is acceptable for testing to ensure rapid delivery of notifications, but is not practical in real world scenarios, and may negatively impact your end user’s mobile device battery usage.

Weighting: Weighting prioritizes competing notifications using the same trigger. For example, if you have several Geofence Enter Events, you can use the Weighting field to prioritize which of the Geofence Enter Events will fire on an end user’s device, depending on certain conditions, including user values like age, gender, etc.

Category: Setting a Category on your Event allows you to gather click through rate data on your Event. Type in a term to populate possible category options to select from. While this field is optional and not required to trigger Events, it is required to obtain click through rate data on Click Through Rate widget.

Group: The Group associated with the Event. A Group is the association of one or more Proximity Technologies, and it provides a convenient way to associate multiple Proximity Technology triggers with an Event.

Trigger (Required): Multi-option field to select one or more proximity triggers for the event (NFC tap, QR scan, Geofence Enter/Dwell/Exit, etc).

Once these fields have been configured, click the Update button to save changes.

NOTE: If there are issues with a required field, you will not be able to Update the settings until you resolve the issue.

Yes No Suggest edit
Last updated on February 16, 2016

Scheduling

06-eventscheduling

Scheduling settings:

All Day checkbox: This allows you to configure whether the event can trigger at any time of day or at a specific time. If the Event should be active within a specific window of time, you will need to select a Start Time and End Time after setting the Start Date.Times here are shown in 24hr format.

Start Date (Required): Check this box to establish a start date for your event. You can either type the date manually (the format is yyyy-mm-dd), or you can click the calendar button to select the date on a calendar popup. If you’ve unchecked the All Day checkbox, you can set the time when you want the events to start.

End Occurrence checkbox: This enables you to set an end date for your event. If the checkbox is unchecked, the system assumes there is no end date for the event. If you do have an end date, check the box for the End Date field, where you can either manually fill in your end date, or select using the calendar popup.

Repeat checkbox: Allows you to set a recurrence for the event. You can select options including: every day, specific days of the week, specific days of the month, and specific days of the year.

Caution: If the Event spans several days, you must select a recurrence of the Event. Without a recurrence, the system will only list the Event for the first day.  For example, if the Event is set to run every day between March 1 through March 30, you need to:

  • Set Start Date to 3/1/2016
  • Set End Date as 3/31/2016
  • Click Repeat Checkbox, and set recurrence to Daily

Once these fields have been configured, remember to click the Update button to save progress.

NOTE: If there are issues with a required field, you will not be able to Update the settings until you resolve the issue.

Yes No Suggest edit
Last updated on February 16, 2016

Conditions

07-eventconditions

Conditions on Events allow control over which Events are triggered based on a set of criteria. Any custom attributes the client sends, customer demographic information, or built-in device states (such as battery life, charging state, or network connected state) can be used to prioritize or prevent notifications from firing on the device.

For example, your Geofence Dwell Event triggers a YouTube video as the Action. However, the video is long, and (not wanting to impact mobile data caps), you only want end users to watch the video if they connected to Wi-Fi. In this scenario, you can set a condition to look at DeviceConnectedtoNetwork.

This condition sets a filter so that only users connected to Wi-Fi receive the notification prompting them to watch the YouTube video. Users connected via the cellular network will not receive this video notification.

Yes No Suggest edit
Last updated on February 16, 2016

Deleting Events

To delete an Event, click into the Edit Group widget for the Event you’d like to delete from the table, and click the Delete button in the upper-right hand corner of the widget.

05-basicinfo (1)

A confirmation box appears, asking you to confirm the deletion. Click OK to proceed.

11-deleteconfirm

Note: The Delete option is irreversible and any usage data or traffic data captured may be lost.

Yes No Suggest edit
Last updated on February 23, 2016

Duplicating Events

To Duplicate an Event, click into the Edit Group widget for the Event you’d like to duplicate from the table, and click the Duplicate button in the upper-right hand corner of the widget.

05-basicinfo (1)

A confirmation box appears, asking you to confirm the duplication. Click OK to proceed.

13-dupconfirm

After the duplicated Event is created, you can edit the fields in the sections to customize the duplicated Event.

Yes No Suggest edit
Last updated on February 23, 2016

Variables

You can add optional Variables to your Events.
07a-variables

Variables can be used like meta-tags to track interactions or pass along tracking information to assist with reporting usage and transactions with your Events.

Attribute is a free text field for a unique identifier of a group of data.
Value is a free text field for the actual data in that group.

Once you’ve added an Attribute and Value, click the Add button to save.

Yes No Suggest edit
Last updated on February 18, 2016

Action

07a1-eventactions

Use the Action widget to configure Actions related to your Event.

Clicking the hyperlink next to Action will allow you to select your action from the drop-down menu for your Event. Based on the selection made, the Action type settings will update dynamically.

Action Localization

To localize your Action, click the Add Locale button. This gives you the option of localizing the action based on the end user’s device language setting.

Example: Your action is set to redirect your end users to your website upon entering your business. Your website is translated to French, Spanish and English. To link users to the appropriate localized site, click the Add Locale button, and select the FR and ES options. In the URL field, add the localized versions of your website. When users with FR as their language option on their device interact with your enter event, they will be directed to the FR localized version of your site. Similarly, users with ES will be directed to your ES localized version website. All other customers will be sent to the English language version of your site.

Yes No Suggest edit
Last updated on February 16, 2016

Notification

07b-eventnotification

Set the notification title and text using the Notification widget. The Title and Text field are simple text notifications and can support more than 255 characters, but the number of characters displayed on screen is limited at the device OS level (iOS supports up to 2kb, Android support up to 1024 bytes). To edit these fields, simply click on the text under Title and Text. Once complete, click the checkmark to save.

Notification Localization

To localize your Notification, click the Add Locale button. This gives you the option of localizing the notification displayed on the end user’s device based on the device language setting.

Similar to the Action Localization, you can display a different notification title and text based on the device’s language setting. Click the Add Locale button to select languages and you will be able to localize the notification title and text that appears on the device when the end user triggers your event.

Yes No Suggest edit
Last updated on February 16, 2016

Recent Interactions

07c-eventrecentinteraction

The Recent Interactions widget provides additional metrics, using date or time as a lens to review performance data. For more information on the Recent Interactions widget, please visit the Analytics page.

Yes No Suggest edit
Last updated on February 16, 2016

Event Click Through Rate

07d-eventctr

If the Event has a Category assigned, the Event Click Through Rate widget will display click through rate information on the Event. The headers in this field can be sorted from highest to lowest. The contents of the widget can be searched using search field in the upper left.

You can change the number of entries displayed using the drop-down in the upper right, or if you have more entries than the number of entries displayed, used the Previous and Next buttons to navigate in between the pages.

Yes No Suggest edit
Last updated on February 16, 2016

Traffic

07e-eventtraffic

The Traffic widget lists all traffic against this Event. This differs from the Traffic widget on the Analytics > Triggers page, which shows all traffic on your proximity technologies.

From this table, you can sort and filter on device ID, Source, Platform, Version (referring to the device’s OS version), and Age (the number of days since the traffic record was created). You can also search within the columns using the search box at the top of the table.

The columns in this table can be sorted by clicking on the headers. Each header also includes a searchable text field to filter for specific items.

In the upper left, you can change the number of entries displayed. If you have more Events than number of entries displayed, you can use the Previous and Next buttons in the lower right to navigate in between pages.

To drill down into a specific device, click on the Device ID. Please see the Devices section for more.

Yes No Suggest edit
Last updated on February 16, 2016

Content

The Content section allows the customization of messages on Touch/Scan Actions and Landing Pages.  Additionally, you can create Interstitials and Custom Actions and Scripts via the File Editor.


Yes No Suggest edit
Last updated on February 2, 2016

Touch/Scan Actions

The Touch/Scan Actions section displays a list of the built-in and custom actions that may be assigned to both NFC tags and QR codes. Since push proximity technologies do not require prior installation of an app, the actions will be triggered from the user’s mobile browser following a tap or scan.

Viewing Touch/Scan Actions

  1. To view the Touch/Scan Actions, click on the Content tab.
  2. In the left sidebar click on Touch/Scan Actions.

01-touchscan

Available Actions

The available actions are:

URL Redirect: Redirects the end user to a webpage.

URI: Uniform resource, such as a mailto or a deep link to a mobile app or website

Dial Number: Opens up the phone dialer on the device.

NOTE: On iOS, the Dial Number action will start dialing the number once the end customer activates the notification. On Android, the Dial Number action populates the phone number in the application but will not dial automatically until the user clicks the call button.

SMS: Opens the phone’s SMS app pre-populated with the recipient’s number.

Email Message: Pre-populate an email message using the phone’s email app.

Contact Record: Add a contact record onto the end user’s device.

Bluetooth Pairing: Facilitates pairing the customer’s device to a Bluetooth product, provided the user accepts the pairing.

WiFi Settings: Connects to a WiFi network. This is only available on Android due to restrictions on the iOS platform

Application Store: Opens the platform-appropriate app store to a specific app.

NOTE: If the user does not have the app, they will see the option to install.  If they have the app, they will see an option to open the app.

Twitter: Redirects to a specific Twitter account. If the Twitter app is installed, the action will complete within the Twitter application. If the customer does not have Twitter installed, the action will be completed through the browser.

YouTube: Redirects to a video posted on YouTube.  If the YouTube app is installed, the video will play in the YouTube app.  If the YouTube app is not installed, the video will play in the mobile web browser.


Yes No Suggest edit
Last updated on February 16, 2016

Landing Pages

Landing Pages

The Landing Pages widget displays a list of all the built-in actions available for both NFC tags and QR codes.

You can search for specific Landing Page using the search text field in the upper left, and you can change the number of entries displayed using the drop-down in the upper right.

You can sort your Landing Pages alphabetically by the Name or Description columns.

If the number of Landing Pages is greater than the number of entries displayed, you can use the Previous and Next buttons in the lower right to navigate.

Previewing Landing Pages

Click the magnifying glass icon to open the Action Simulator and preview the landing page for the selected action.

02-previewapp

The Action Simulator provides a preview of the Landing Page upon a Touch or Scan.  You can simulate the experience on a handful of devices (iPhone 5, iPhone 6, HTC One, Nexus 7, Galaxy Y, and iPad Mini), screen orientation (Portrait or Landscape).

Change Environment allows you to simulate the <need clarification>

Editing Landing Pages

You can customize the text in the built-in action Landing Page by clicking the Edit icon to open the Customer Action Editor.

03-editlandingpages

Line 6 includes the text that appears on a Touch/Scan Action Landing Page.  The default value is “This should just take a moment”, but it can be customized.  The content of the text must be placed within the <h4> tags.

After you have edited a built-in action a third Reset icon will appear next to the action in the Landing Pages widget. Click this icon to reset the built-in action.

Yes No Suggest edit
Last updated on February 16, 2016

Custom Actions

Custom

In addition to the built-in actions, you can also create or edit custom actions using the Custom widget.

The Custom widget displays a list of all custom actions available to both NFC tags and QR codes.

04-customwidget

You can search for specific Touch/Scan Custom Actions using the search text field in the upper left, and you can change the number of entries displayed using the drop-down in the upper right.

If the number of Touch/Scan Custom Action is greater than the number of entries displayed, you can use the Previous and Next buttons in the lower right to navigate.

You can sort your Touch/Scan Custom Actions alphabetically by the Name column.

Adding Custom Actions

To add a new Custom Action, click the Add button to open the New Custom Action section.

05-newcustomaction

Assign a name to your Custom Action in the Name field in the Custom Action Info widget.  Clicking the Update button will save your progress and return you to the Touch/Scan Actions page.

Editing Custom Actions

To edit an existing custom action, click the Code Editor icon to open the Custom Action editor.  The Custom Action editor allows you to create your own content to display following a NFC Tap or QR Scan.

The text field supports html code in addition to standard text.

You can preview your Custom Action by clicking the Magnifying Glass button. This will open the Action Simulator.

06-actionsimulator

The Action Simulator provides a preview of the Landing Page upon a Touch or Scan.  You can simulate the experience on a handful of devices (iPhone 5, iPhone 6, HTC One, Nexus 7, Galaxy Y, and iPad Mini), screen orientation (Portrait or Landscape).

Clicking the save button will save your progress.

You can select the Custom Action as an Action at the Tag, Group or Event.

To select Custom Action on the Tag:

  1. Click on the Deployment tab
  2. In the sidebar, click the Touch/Scan Triggers link.
  3. In the Tag widget, click on your Tag.
  4. In the Action widget, use the drop-down to change the Action to Custom Script.

07-changeaction

  1. In the Touch/Scan Script Name field, use the drop-down to select your script;

08-selectscript

Deleting Custom Actions

To delete an existing custom action, click the Code Editor icon to open the Custom Action Editor section and click the Delete button.

A confirmation dialog will appear. Press the OK button to continue.

09-deletactionconfrm

Caution: Deleting this item is irreversible.

Yes No Suggest edit
Last updated on February 16, 2016

Landing Page Branding

In the Landing Page Branding section, you can brand and preview the landing page that appears in the user’s mobile browser when they interact with any of the push proximity technology Touch / Scan actions.

01-branding

 

Yes No Suggest edit
Last updated on February 16, 2016

Interstitial Preview

The Preview widget shows the result of the selections you made on the Branding widget.

NOTE: URL is a placeholder. When the landing page is actually shown to an end-user, the URL of the site you’ve set up for the URL redirect, or a preview of the action to be performed (e.g., App Store, Youtube redirect, etc) will be displayed.

Yes No Suggest edit
Last updated on February 17, 2016

Interstitials

Interstitials are hosted custom web content that is displayed when a user clicks a notification generated by a push proximity technology, such as a geofence, beacon or WiFi network. Interstitials will appear full screen within your app and include a built-in localizable Close button to dismiss the interstitial and return to your app.

The Interstitials widget will display a pageable list of all available interstitials, including the unique ID, name, description, date the interstitial was last updated and by whom.

01-interstitialslist

You can sort any column by clicking the column header. You can browse the actions by clicking the Previous or Next buttons or the specific page number, or change the number of actions displayed per page using the drop-down menu. You can also filter results by entering text  or numbers from any of the columns fromthe Search field.

 

Editing Interstitials

You may edit any existing interstitials using either the Code or WYSIWYG Editor. To edit an interstitial using the Code editor, click the Code Editor icon. To edit an interstitial using the WYSIWYG Editor, click the WYSIWYG Editor icon.

NOTE: When opening the WYSIWYG Editor, you’ll see the following pop-up message:

02-wysiwygconfirm

If you used the WYSIWYG Editor to create your Interstitial, please disregard and click Continue. If you used the Code Editor, you can click Continue and proceed. However, we strongly recommend using the Preview options to view your Interstitial to ensure that initial settings have not been overwritten.

Previewing Interstitials

You can preview interstitials using the Action Simulator. The Action Simulator lets you display your interstitials as they will appear on a number of different device and screen types.

When you click on the magnifying glass to preview, the Action Simulator opens with your Interstitial content.

07-actionsimulator

Clicking the menu in the upper right of the Action Simulator provides the following options

Devices: Preview the message on a variety of iOS and Android phones and tablets.

Orientation: Simulate the message in landscape or portrait mode.

Change Environment: Change attributes such as number of taps/scans, associated groups, location, etc to support testing efforts.


Yes No Suggest edit
Last updated on February 16, 2016

Adding a New Interstitial with the WYSIWYG Editor

You can create a new Interstitial using the built-in WYSIWYG (What You See Is What You Get) editor by clicking the Add button then clicking the Use WYSIWYG Editor button from the dialog that appears.

02-wysiwygconfirm

This will open the built-in WYSIWYG Editor where you can create and format content just as if you’re typing in a word processing application.

The WYSIWYG Editor includes the following two widgets:

Yes No Suggest edit
Last updated on February 18, 2016

Interstitial Info

Enter the Name and Description for the Interstitial in the Interstitial Info widget. A default name will automatically be created for the interstitial. You can update the name at any time using the Name field. Click the Update button to apply your changes.

The WYSIWYG Editor is included below the name and description fields.

03-wysiwygeditor

The WYSIWYG editor allows you to create and edit your interstitial using a visual interface. The editor includes multiple toolbar rows for formatting your content and inserting special pre-formatted content, such as tables and graphs.

The toolbar includes options for multiple formatting options similar to the options available in a Word Processing application.  You can also insert images, web links and videos.

Click the Update button to save your content.

Yes No Suggest edit
Last updated on February 16, 2016

Your Files

The Your Files widget links to the File Manager, which you can use to call up saved CSS files, images, and javascript files, or add new files and directories. To store files in the File Manager, simply drag and drop your files into the desired directory, or select the file by navigating through the appropriate folders on your computer.

01-filemanager

For example, you want to save an image of your company’s logo in order to include it on your Interstitials.

  1. Either Drag and Drop the image file or click on the “Drop files to upload” area
  2. Once the image has uploaded, it will appear in the directory to the left. Clicking on the image provides the static URL of the image.

02-fileupload

  1. When creating your interstitials, you can reference that URL through <a href> tag to display the image.

To delete the file, click the Delete button.

Caution: Deleting the file in this widget does not provide a warning dialog.  If you delete the file in error, you will need to re-upload the file.

Yes No Suggest edit
Last updated on February 16, 2016

Adding a New Interstitial with the Code Editor

You can create a new Interstitial using the Code Editor by clicking the Add button then clicking the Use Code Editor button from the dialog that appears.

This opens the Code Editor, where you can create your interstitial using scripting directly.

The Code Editor includes the following widgets:

Yes No Suggest edit
Last updated on February 17, 2016

Interstitial Info

The Interstitial Info widget lets you enter the Name and Description for the Interstitial. A default name will automatically be created for the interstitial. You can update the name at any time using the Name field. Click the Update button to apply your changes.

Yes No Suggest edit
Last updated on February 16, 2016

Your Files

The Your Files widget links to the File Manager, which you can use to call up saved CSS files, images, and javascript files, or add new files and directories. To store files in the File Manager, simply drag and drop your files into the desired directory, or select the file by navigating through the appropriate folders on your computer.

05-filemanager

For example, you want to save an image of your company’s logo in order to include it on your Interstitials.

  1. Either Drag and Drop the image file or click on the “Drop files to upload” area
  2. Once the image has uploaded, it will appear in the directory to the left. Clicking on the image provides the static URL of the image.

06-fileupload

  1. When creating your interstitials, you can reference that URL through <a href> tag to display the image.

To delete the file, click the Delete button.

Caution: Deleting the file in this widget does not provide a warning dialog.  If you delete the file in error, you will need to re-upload the file.

Yes No Suggest edit
Last updated on February 16, 2016

Web Page

Add the content of your interstitial in the Web Page widget. The Code Editor behaves the same as any basic code text editor. The editor includes a number of built-in color themes which you may select from by clicking the Theme drop-down menu. You may also modify the displayed text size within the editor by clicking the Font size drop-down menu.

To preview your interstitial click the Magnifying Glass icon to open the Action Simulator. To save your work, click the Disk icon, you will see a notification in the upper right hand corner of the screen once the file has been saved.

Yes No Suggest edit
Last updated on February 16, 2016

Deployment

The Deployment tab allows you to manage your Groups and Proximity Technologies.  Along the left sidebar, it is separated into the following:

  • Groups: Groups are the association of one or more Proximity technologies, such as Geofences or Beacons. It provides a convenient way to associate multiple proximity triggers with individual events.
  • Wireless Triggers: Wireless Triggers represent the “Push” Technologies:

Geofences: Geofences are a Proximity technology that cover a larger area than a Wifi Network and Beacon. It is a virtual perimeter around a specific location. The coverage area is established by a radius from that specific location.

Beacons: Beacons are a Proximity technology used in shorter range situations than Geofences, typically indoors.  

Wi-Fi Networks: Wi-Fi Networks can be used as a Proximity technology. It can provide slightly more range than a Beacon.

  • Touch/Scan Triggers: Touch/Scan Triggers represent the “Pull” or “Touch” Technologies, NFC and QR

Yes No Suggest edit
Last updated on February 8, 2016

Groups

A Group is the association of one or more Proximity Technologies, such as Geofences and Beacons. It provides a convenient way to associate multiple Proximity Technologies with an individual Event. Groups allow you to bucket your proximity technologies based on real-world deployment, such as by store location or collateral type.

 


Yes No Suggest edit
Last updated on February 17, 2016

Managing Your Groups

To manage the Groups in your account:

  1. Click on the Deployment tab
  2. In the sidebar, click Groups

01-groupswidget

The Groups table displays the Groups and the following settings in your account:

ID: This is the identifier the system assigns to your Group.

Name: This is the name of your Group, set by you, or auto-generated by the system when the Group was added to the account.

Description: This is your description of your Group.

Tags: Displays the number of Tags assigned to your Group.

Events: Displays the number of Events assigned to your Group.

Beacons: Displays the number of Beacons assigned to your Group.

Geofences: Displays the number of Geofences assigned to your Group.

Wi-Fi Networks: Displays the number of Wi-Fi Networks assigned to your Group.

Locked: A numerical value indicating whether the Group is Not Locked (‘0’) or Locked (‘1’).

Loc. Req: A numerical value indicating whether the Group is set to Never Ask (‘0’), Always Ask (‘1’) or Smart (‘2’).

Navigating the Groups Table

To pin this table to the Dashboard, click the Pin button in the Widget Heading Bar. pinned

A table or widget that has successfully been pinned will appear like this: unpinned

To unpin, re-click the Pin button.

The columns in this table can be sorted by clicking on the headers. Each header also includes a searchable text field to filter for specific items.

In the upper left, you can change the number of entries displayed.  If you have more Groups than number of entries displayed, you can use the Previous and Next buttons in the lower right to navigate in between pages.

Exporting Table Contents

Clicking the Copy button allows you to copy your Groups to paste into a different document.

Clicking the CSV, Excel or PDF buttons allows you to save a document locally as that file type.

Clicking the Print button provides a Print Preview version of the table.  Clicking the “ESC” key will return you to the Administrator.

03-groupslist

Yes No Suggest edit
Last updated on February 18, 2016

Adding or Editing Groups

From the Deployment tab, click Groups from the sidebar. Then, to create a new Group, click the Add button. To edit the settings for an existing Group, click on the Group name to access its Edit Group page.

The Edit Group widget includes two different tabs: Group Information, and Action Details.

04-addeditgroup

Group Information

Group Information settings:

Enter in the name of your Group. The Group Name shows up in the Group table and also in the drop-down lists used throughout the account to associate proximity technologies, like Geofences and Beacons, to a specific Group.Description: This is the long text description of the Group that is displayed in the Group page.

Locked: This is applicable to NFC Tags and QR Codes only. This option provides a mechanism for easily setting the same action for multiple NFC Tags and QR Codes, rather than configuring each tag and code individually. The options are Locked and Not Locked.

  • In a Locked group, any NFC Tags/QR Codes associated with the group will perform the group-level action rather than the action defined at the individual NFC tag or QR Code level.
  • In an Not Locked group, the NFC Tag/QR Code will perform the actions defined at the individual NFC Tag or QR code level.

Location: This is also specific to NFC Tags and QR Codes. This option determines if the location of the tag or code will be set via the user’s browser location services.

  • Never Ask will never ask the end user for their location on each scan or tap.
  • Always will always ask the end user for their location on each scan or tap.
  • Smart will ask once and remember the selection made by the first user to provide a location. It will only update the location if a more accurate location is provided by a subsequent user.

ID: This is the ID assigned to the Group.

Tag: This shows the number of Tags assigned to the group.

Created: This shows the time and date the Group was created.

Yes No Suggest edit
Last updated on February 17, 2016

Action Details

In the Action Details widget, you can set default actions for the NFC Tags or QR Codes associated with the Group. The Locked option must be enabled for the defined action to apply to all associated NFC tags or QR codes. Please visit the Content page for further content around Actions.

04a-widgetizedactionlocale

Clicking the Add Locale button gives the user the ability to provide localized actions that are based on the language settings on the end user’s mobile device. Select the language in the drop-down menu.

05-localize (1)

In the Locale menu, you can select languages (example: EN, FR), or the language and region (example: EN-US, EN-UK, FR-FR, FR-CA). If the user’s mobile device uses a language that has not been selected in the Select Locale menu, the user will receive the default action.

For more information about Localization, please visit the Campaigns page.

Default action hierarchy

The default action for NFC Tags and QR Codes in a Group are performed according to the following hierarchy.

Event: For Tags in a Group, the Action based on an Event supersedes all other actions.

Example: I have an Event with a QR Scan as the trigger. That Event has a Twitter Action, but the Group (which is Locked) has an Action of URL Redirect, and the QR Code has an Action of a YouTube video. Because the Event has the Twitter Action, when the end user scans the QR code, they will go to Twitter.

Group: If the parent Group is set to Locked, the Action on the Group supersedes any Actions set at the individual tag level. The requirement for this is that the Group must be set to Locked.

Tag: Finally, if I have some tags associated with my Group, and each tag has it’s own separate action, If the Group is unlocked, the Group’s Action is not recognized, then the Actions encoded on the individual tag will take effect.

Yes No Suggest edit
Last updated on February 17, 2016

Events

The Events table shows the Events assigned to this Group. For more information on Events, please visit the Events page.

Yes No Suggest edit
Last updated on February 17, 2016

Beacons

The Beacons table shows the Beacons Assigned to this Group. For more information on Beacons, please visit the Beacons page.

Yes No Suggest edit
Last updated on February 17, 2016

Geofences

The Geofences table shows the Geofences assigned to this Group. For more information on Geofences, please visit the Geofences page.

Yes No Suggest edit
Last updated on February 17, 2016

Wi-Fi Networks

The Wi-Fi Networks table shows the Wi-Fi Networks assigned to this Group. For more information Wi-Fi Networks, please visit the Wi-Fi Networks page.

Yes No Suggest edit
Last updated on February 17, 2016

Recent Interactions

The Recent Interactions widget shows a summary of recent transitions, engagements and installations. For more information on the data in the Recent Interactions widget, please visit the Triggers page in the Analytics Tab.

Yes No Suggest edit
Last updated on February 17, 2016

Platforms

The Platforms widget shows a chart of the platforms used to engage with your Proximity Technologies.

05a-platformgroup

Yes No Suggest edit
Last updated on February 17, 2016

Browsers

The Browsers widget shows a chart of the Browsers used to display content.

05b-browsergroup

Yes No Suggest edit
Last updated on February 17, 2016

Traffic

The Traffic widget shows all transitions for proximity technologies assigned to this Group. For more information on this widget, please visit the Triggers page.

05d-trafficgroup

Yes No Suggest edit
Last updated on February 17, 2016

Calendar

The Calendar widget shows all Events assigned to this Group. For more information on this widget, please visit the Calendar page.

Yes No Suggest edit
Last updated on February 17, 2016

Recent Engagements

The Recent Engagements widget shows all recent actions from proximity technologies and events assigned to this Group.

05e-recentengagementgroup

Yes No Suggest edit
Last updated on February 17, 2016

Map

The Map widget shows recent engagement on a map. You can click on the pins, and zoom in and zoom out on the map.

05f-mapgroup

Yes No Suggest edit
Last updated on February 17, 2016

Delete Groups

To delete a Group, click into the Edit Group widget for the Group you’d like to delete from the table, and click the Delete button in the upper-right hand corner of the widget.

06-deletegroup

A confirmation box appears, asking you to confirm the deletion. Click OK to proceed.

07-deletegroupconfirm

NOTE: The Delete option is irreversible and any usage data or traffic data captured may be lost.

Yes No Suggest edit
Last updated on February 17, 2016

Geofences

Geofences are virtual perimeters around specific locations, and can be used as a Proximity Technology within your campaigns. A Geofence coverage area is established by a radius from a specific location, and typically covers a larger area than a Wi-Fi Network or Beacon. Geofences are optimal for larger venues and outdoor uses.

Geofences relevant to your campaigns may be added to your account from the Geofences section.  

Yes No Suggest edit
Last updated on February 17, 2016

Managing Your Geofences

To manage the Geofences in your account:

  1. Click on the Deployment tab.
  2. In the sidebar, click the Wireless Triggers option.
  3. Click on Geofences.

01-geofenceslist

The Geofences table displays the Geofences and the following settings in your account:

ID: This is the identifier the system assigns to your Geofence.

Name: This is the name of your Geofence, set by you, or auto-generated by the system when the Geofence was added to the account.

Radius: This is the coverage area of your Geofence. You set this value when adding the Geofence to the account.

Dwell: This is the amount of time (in seconds) a user will need to remain inside your Geofence to trigger a Dwell-based Event.

Latitude: This is the latitude of your Geofence.

Longitude: This is the longitude of your Geofence. When creating or editing your Geofence, you can either type in your latitude and longitude, or search for your location or address to have the latitude and longitude auto-fill.

Group: The Group your Geofence is assigned to.

Timezone: The timezone the Geofence resides in. This value is auto-populated based on the Latitude and Longitude of your Geofence.

Navigating the Geofences Table

To pin this table to the Dashboard, click the Pin button in the Widget Heading Bar. pinned

A table or widget that has successfully been pinned will appear like this: unpinned

To unpin, re-click the Pin button.

The columns in this table can be sorted by clicking on the headers.  Each header also includes a searchable text field to filter for specific items.

In the upper left, you can change the number of entries displayed.  If you have more Geofences than number of entries displayed, you can use the Previous and Next buttons in the lower right to navigate in between pages.

Exporting Table Data

Clicking the Copy button allows you to copy your Geofences to paste into a different document.

02-copygeofence

Clicking the CSV, Excel or PDF buttons allows you to save a document locally as that file type.

Clicking the Print button provides a Print Preview version of the table.  Clicking the “ESC” key will return you to the Administrator.

04-printgeofence

Yes No Suggest edit
Last updated on February 18, 2016

Adding or Editing a Geofence

From the Deployment tab, click on Wireless Triggers, then Geofences in the left-hand sidebar. Then, click the Add button above the Geofences table. To edit the settings for an existing Geofence, click on the Geofence name to access its Edit Geofence page.

Geofence settings

05-geofencesettings

In the Edit Geofence widget, you’ll see the following settings.

Name: Free text field you can use to name your Geofence. During geofence creation, the system will auto-fill this field, which you can edit at any time. The Name will be displayed in the Geofence table.

Latitude and Longitude (Required): Sets the epicenter of the geofence. This field can either be manually populated, or auto-filled using the Location widget on the right.

Radius (Required): Sets the boundary of the coverage area (in meters) from the location (as defined by the latitude and longitude). You’ll see a graphical representation of the coverage area in the map on the right for reference. Default is 100 meters.

Dwell: Refers to the amount of time (in seconds) the end user needs to remain within the Geofence to trigger a dwell event. If Geofence Dwell is not used as an Event trigger, the Dwell field is not required.

BLE Scan: This toggle will prompt the SDK to scan for known Beacons within this Geofence.

NOTE: Our general recommendation is to enable BLE Scan within the Geofence by setting the toggle to On, as limiting scans for Beacons until a device is inside a Geofence helps to reduce battery consumption.

Timezone: This value is auto-populated using the the location of the Geofence. If the Geofence is in California, the time zone changes to America/Los_Angeles. Move the Geofence to Manhattan, and the time zone will change to America/New_York.

Group:  Select the Group to which this Geofence will be associated from the drop-down list. If you do not have any Groups created, you can leave this selection blank, but in order to use this Geofence in  a campaign, you will need to associate a Group. Please visit the Groups page for further content around Groups.

Once these fields have been configured, click Update.

NOTE: If there are issues with a required field, you will not be able to Update the settings until you resolve the issue.

Location Widget

If you do not know the Latitude and Longitude of a location, or would rather use the address of a location, type the address, location name, or business category name of your desired Geofence location into the Location widget, and the system will update the latitude and longitude in the Geofence settings automatically. You can also drag and drop the location pin to your desired location.

Within the Map, you can also zoom in and zoom out to pinpoint your location, or click and drag to move the map around.

Yes No Suggest edit
Last updated on February 17, 2016

Location Widget

If you do not know the Latitude and Longitude of a location, or would rather use the address of a location, type the address, location name, or business category name of your desired Geofence location into the Location widget, and the system will update the latitude and longitude in the Geofence settings automatically. You can also drag and drop the location pin to your desired location.

Within the Map, you can also zoom in and zoom out to pinpoint your location, or click and drag to move the map around.

Yes No Suggest edit
Last updated on February 17, 2016

Variables

You can add optional Variables to your Proximity Technologies (Geofences, Beacons, Wi-Fi Networks and Tags) or Events.

Variables can be used like meta-tags to track interactions or pass along tracking information to assist with reporting usage and transactions with your Geofences, Beacons, Wi-Fi Networks, Tags, and Events.

05-variables

Attribute is a free text field for a unique identifier of a group of data.

Value is a free text field for the actual data in that group.

Once you’ve added an Attribute and Value, click the Add button to save.

Example: I deploy several Geofences around points of interest in Seattle, WA. I add a tracking variable so that I can easily filter my transition data for interactions around specific points of interest. I add a Variable with an Attribute (“Location_Name”), and a Value (i.e. “Smartwhere Office” or “Space Needle”) to each Geofence. By adding that Variable, I can see which interactions involved the Geofence around the Smartwhere Office or the Space Needle when I review Geofence traffic data.

I can also further customize a user’s experience using this Variable. By configuring my Event and Action to run a script referencing the “Location_Name” Attribute as a part of its notification, the “Location_Name” Value would be used in the notification title or text (i.e. “Welcome to {LOCATION_NAME}!”).

Yes No Suggest edit
Last updated on February 17, 2016

Recent Transitions

The Recent Transition widget displays the ten most recent transitions against this Geofence. The widget shows the type of transition (Enter, Dwell, Exit), the device and the timestamp when the transition occurred.

05a-geofencerecent

Yes No Suggest edit
Last updated on February 17, 2016

Traffic

The Traffic widget lists all traffic against this Geofence (Geofence Enter, Geofence Dwell, Geofence Exit). This differs from the Traffic widget on the Analytics > Triggers page, which shows all traffic on your proximity technologies.

From this table, you can sort and filter on device ID, Source (or Transition type), Platform, Version (referring to the device’s OS version), and Age (the number of days since the traffic record was created). You can also search within the columns using the search box at the top of the table.

The columns in this table can be sorted by clicking on the headers. Each header also includes a searchable text field to filter for specific items.

In the upper left, you can change the number of entries displayed. If you have more Tag IDs than number of entries displayed, you can use the Previous and Next buttons in the lower right to navigate in between pages.

To drill down into a specific device, click on the Device ID. Please see the Device section for more.

05b-gftraffic

Yes No Suggest edit
Last updated on February 17, 2016

Calendar

The Calendar widget shows all scheduled Events. For more information, please visit the Calendar page.

Yes No Suggest edit
Last updated on February 17, 2016

Deleting Geofences

To delete a Geofence, click into the Edit Geofence widget for the Geofence you’d like to delete from the table, and click the Delete button in the upper-right hand corner of the widget.

06-deletegeofence

A confirmation box appears, asking you to confirm the deletion.  Click OK to proceed.

07-deletegeoconfirm

NOTE: The Delete option is irreversible and any usage data or traffic data captured may be lost.

Yes No Suggest edit
Last updated on February 17, 2016

Adding Multiple Geofences Using Bulk Upload

To add multiple Geofences in bulk, create a CSV file with the Geofence settings and upload it to your account using the Upload button.

Headers for bulk upload

In a CSV file, use the following headers (note the use of lowercase in the headers). For detailed information about the fields, please see the Geofence settings section above.

name

radius

latitude

longitude: If you don’t have the latitude and longitude of a location, you may need to use a latitude and longitude converter to convert an address to latitude and longitude.

dwell (in seconds)

blescan:“1” (on) or “0” (off).

group_id: The Group ID you wish to associate this Geofence to. To find the Group ID, go to the Deployment tab, click Groups in the left sidebar. In the Groups widget, the left most column will provide the Group ID.

NOTE: If you enter in a Group ID that is not in your account, the CSV upload will fail.

timezone: You can leave this field blank — The timezone will auto-fill based on your Geofence location after the upload completes.

refresh_on_exit: “1” (Yes) or “0” (No).

Uploading your CSV

  1. Once you’ve populated your CSV, save it as a CSV file.
  2. Click the Upload button.

08-uploadgeofence

  1. Either drag and drop your CSV file into the appropriate area, or click into the window and browse to the saved CSV file.
  2. If the CSV upload is successful, a green checkmark will appear.

09-uploadgeosuccess

  1. If the upload is unsuccessful, a red X will appear. Please contact Smartwhere Support, including the CSV file, for assistance.

10-uploadgeofail

 

Yes No Suggest edit
Last updated on February 17, 2016

Beacons

Bluetooth Low Energy (BLE) Beacon, Bluetooth 4.0, Bluetooth Smart, or iBeacon (Beacon will be the terminology moving forward) is a Proximity Technology used in situations requiring more precision from a location accuracy. The actual range varies from device to device, but typical range is around 30 meters/90 feet.

A Beacon broadcasts a unique ID that is received by a mobile application when users enter or exit (or dwell or hover) within range of the Beacon’s broadcast. Smartwhere’s SDK recognizes that unique ID, and performs an action based on a trigger and Event. The trigger and the Action are configured in the Campaigns section.

Beacons relevant to your campaigns may be added to your account from the Beacons section.  

Yes No Suggest edit
Last updated on February 17, 2016

Managing Your Beacons

To manage the Beacons in your account:

  1. Click on the Deployment tab.
  2. From there, click on Wireless Triggers in the left sidebar. Clicking Wireless Triggers expands the menu to navigate managing your Geofences, Beacons and Wi-Fi Networks.
  3. Click on Beacons.

01-beaconslist

The Beacons table displays the Beacons and the following settings in your account:

ID: This is the identifier the system assigns to your Beacon.

Name: This is the name of your Beacon, set by you, or auto-generated by the system when the Beacon was added to the account.

UUID: Universally Unique Identifier (UUID) of the Beacon. You enter this value when adding the Beacon to the account.

Major: Along with the UUID and Minor, this is an integer between 1 to 65535 set by the Beacon manufacturer to enable the uniqueness of the Beacon.

Minor: Along with the UUID and Major, this is an integer between 1 to 65535 set by the Beacon manufacturer to enable the uniqueness of the Beacon.

Hover: This is the amount of time (in seconds) a user will need to remain in very close proximity to the Beacon (within 1 meter) to trigger a Hover based Event.

Dwell: This is the amount of time (in seconds) a user will need to remain inside the Beacon’s transmission to trigger a Dwell-based Event.

Group: The Group the Beacon is assigned to.

Timezone: The timezone the Beacon resides in. This value is auto-populated based on the location of your Beacon.

Navigating the Beacons Table

To pin this table to the Dashboard, click the Pin button in the Widget Heading Bar. pinned

A table or widget that has successfully been pinned will appear like this: unpinned

To unpin, re-click the Pin button.

The columns in this table can be sorted by clicking on the headers. Each header also includes a searchable text field to filter for specific items.

In the upper left, you can change the number of entries displayed. If there are more Tags than number of entries displayed, you can use the Previous and Next buttons in the lower right to navigate in between pages.

Exporting Table Contents

Clicking the Copy button allows you to copy your Beacons to paste into a different document.

02-beaconcopy

Clicking the CSV, Excel or PDF buttons allows you to save a document locally as that file type.

Clicking the Print button provides a Print Preview version of the table. Clicking the “ESC” key will return you to the Administrator.

04-beaconprint

Yes No Suggest edit
Last updated on February 17, 2016

Unique Beacon Identifiers

To use a Beacon on the Smartwhere platform, you need the following information, which is provided by the Beacon manufacturer:

UUID (Universally Unique Identifier): The UUID is represented by 32 lowercase hexadecimal digits, displayed in five groups separated by hyphens in the following format:  XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX.

Major/Minor: These values are used in conjunction with the UUID to enable the uniqueness of the Beacon. Major and Minor can be integer values between 1 to 65535. If the Major and Minor provided by the manufacturer is in hexadecimal format (e.g. 0x7C09), you can use a hex-to-decimal converter to get 31753.

NOTE: Uniqueness of the Major and Minor values, as well as of the UUID,provides a number of benefits. For one, Beacon management in a large scale deployment will provide richer usage data on which Beacons are currently in use and where traffic is being generated. The Major value could be assigned to a location or store, and the Minor value could be a sequential value for each Beacon deployed in the location or store. This will allow you to retrieve information on high-volume locations/stores, and which Beacons within each stores are being used. As an alternative, Beacons can be configured with the same Major and Minor values, which makes management very simple, but segmented data for each store and beacon is potentially lost.

For UUIDs, especially in an environment where several Beacons are deployed, having a rotating UUID will ensure proper transitions from Beacon to Beacon.

The Beacon manufacturer should be able to assist in customization of the UUID, Major and Minor when you order.

Yes No Suggest edit
Last updated on February 17, 2016

Adding or Editing Beacons

From the Deployment tab, click on Wireless Triggers in the sidebar, then Beacons. To add a new Beacon, click the Add button above the Beacons table. To edit the settings for an existing Beacon, click on the Beacon name to access its Edit Beacon page.

Beacon settings

05-beaconsettings

In the Edit Beacon widget, you’ll see the following settings:

Name (Required): Free text field you can use to name your Beacon. The system will auto-fill this field, which you can edit at any time. The Name will be displayed in the Beacon table.

UUID (Universally Unique Identifier): The UUID helps identify your Beacon and is provided by the Beacon manufacturer.

Major and Minor: Another value provided by the Beacon manufacturer and, along with the UUID, help identify your Beacons.

NOTE: If your Beacon comes with a Major and Minor represented as a hexadecimal value, use a hexadecimal-to-decimal converter to get the integer value. If you haven’t used a converter before, we recommend searching on for a hexadecimal-to-decimal converter.

Latitude/Longitude: This field can either be manually populated, or auto-filled using the Location widget on the right. This will provide a latitude and longitude of the Beacon location, and also captures the appropriate timezone for this location.

RSSI 1M (Received Signal Strength Indicator): This field should be left blank. The RSSI is a measurement of the Beacon’s signal strength. When a Beacon broadcasts, it also sends a measurement for RSSI at 1 meter. If the RSSI from the end user’s device is greater than the manufacturer’s calibrated measurement of RSSI at 1 meter, then the customer is within one meter of the Beacon.

Dwell: Refers to the amount of time (in seconds) a user must be within a Beacon’s coverage area (i.e. they’ve triggered an Enter event, but have not triggered an Exit event) before a Dwell-based action is triggered.

Hover: Refers to the amount of time (in seconds) a customer needs to be in very close range (approximately 1 meter) of the Beacon before a Hover-based action is triggered.

Note: The Hover action differs from Dwell because it does not require a Enter event before triggering an action.

Beacon Name: This refers to the actual Beacon name, and not the name assigned previously.  When adding Beacons individually, this is not an editable field.  It can be added when adding Beacons in bulk.

Timezone: This value is auto-populated using the the location of the Beacon.

Group: Select the Group to which this beacon will be associated from the drop-down list. If you do not have any Groups created, you can leave this selection blank, but in order to use this Beacon in a campaign, the Beacon will need to be associated to a Group. Please visit the Groups page for further content relating to Groups.

Once these fields have been configured, click Update.

NOTE: If there are issues with a required field, you will not be able to Update the settings until you resolve the issue.

Location widget

If you do not know the Latitude and Longitude of a location, or would rather use the address of a location, type the address, location name, or business category name of your desired Beacon location into the Location widget, and the system will update the latitude and longitude in the Beacon settings automatically. You can also drag and drop the location pin to your desired location.

Within the Map, you can also zoom in and zoom out to pinpoint your location, or click and drag to move the map around.

A Note on iOS Devices: For iOS devices, there is an additional step that must be taken to ensure that Beacon-based notifications are triggered. The only way for an iOS device to find a Beacon is for the OS to find it. As a result, you must specify the UUIDs that the application should find in your account. To ensure your application is able to detect the UUID on an iOS device, please visit the Application ID page.

A Note on Android Devices: For Android devices, to help conserve battery consumption,, you should allow BLE Scanning on Geofences and Wi-Fi Networks. This prevents the device from constantly scanning for Beacons, and enables the device to scan for Beacon UUIDs only within a specific area. Without the Scan Option enabled, BLE events cannot be enabled on Android.

Yes No Suggest edit
Last updated on February 17, 2016

Variables

You can add optional Variables to your Beacons.

Variables can be used like meta-tags to track interactions or pass along tracking information to assist with reporting usage and transactions with your Beacons.

05-variables (1)

Attribute is a free text field for a unique identifier of a group of data.

Value is a free text field for the actual data in that group.

Once you’ve added an Attribute and Value, click the Add button to save.

Example: I deploy several Beacons in my event venue. I add a tracking variable so that I can easily filter my transition data so that I can track which Beacons are seeing the most interactions. I add a Variable with an Attribute (“Beacon_Name”), and a Value (i.e. “Beacon 001”) to each Beacon. By adding that Variable, I can see which Beacons saw the most traffic when I review Geofence traffic data.

I can also further customize a user’s experience using this Variable. By configuring my Event and Action to run a script referencing the attribute and value as a part of its notification, the value could be used in the notification title or text (i.e. “You’re next to {value}”).

Yes No Suggest edit
Last updated on February 17, 2016

Recent Interactions

The Recent Transition widget displays the ten most recent transitions against this Beacon. The widget shows the type of transition (Enter, Dwell, Exit and Hover), the device and the timestamp when the transition occurred.

05a-beaconrecentinteraction

Yes No Suggest edit
Last updated on February 17, 2016

Traffic

The Traffic widget lists all traffic against this Beacon (BLE Enter, BLE Dwell, BLE Exit, BLE Hover). This differs from the Traffic widget on the Analytics > Triggers page, which shows all traffic on your proximity technologies.

From this table, you can sort and filter on device ID, Source (or Transition type), Platform, Version (referring to the device’s OS version), and Age (the number of days since the traffic record was created). You can also search within the columns using the search box at the top of the table.

The columns in this table can be sorted by clicking on the headers. Each header also includes a searchable text field to filter for specific items.

In the upper left, you can change the number of entries displayed. If you have more Tag IDs than number of entries displayed, you can use the Previous and Next buttons in the lower right to navigate in between pages.

To drill down into a specific device, click on the Device ID. Please see the Device section for more.

05b-bletraffic

Yes No Suggest edit
Last updated on February 17, 2016

Event

The Event widget shows all scheduled Events. For more information, please visit the Event page.

Yes No Suggest edit
Last updated on February 17, 2016

Deleting Beacons

To delete a Beacon, click into the Edit Beacon widget for the Beacon you’d like to delete from the table, and click the Delete button in the upper-right hand corner of the widget.

06-deletebeacon

A confirmation box appears, asking you to confirm the deletion.  Click OK to proceed.

07-deletebeaconconfirm

NOTE: The Delete option is irreversible and any usage data or traffic data captured may be lost.

Yes No Suggest edit
Last updated on February 17, 2016

Adding Multiple Beacons Using Bulk Upload

To add multiple Beacons, create a CSV file with the Beacon settings and upload to your account using the Upload button.

Headers for bulk upload

In a CSV file, use the following headers (note the use of lowercase). For detailed information about each fields, please see the Beacon settings section above.

name

uuid

latitude

longitude

dwell (in seconds)

hover (in seconds)

major

minor

timezone: You can leave this field blank — The timezone will auto-fill based on your Geofence location after the upload completes.

group_id: The Group ID you wish to associate this Beacons to. To find the Group ID, select the Deployment tab, click Groups in the left sidebar. In the Groups widget, the leftmost column will provide the Group ID. Note: If you input a Group ID that is not in your account, the CSV upload will fail

beacon_name: This is where you can customize the Beacon’s name. It can also be left blank.

rssi_1m: As this value is not currently used, you can either leave it blank, or enter “0”.

Uploading your CSV

  1. Once you’ve populated your CSV, save it as a CSV file.
  2. Click the Upload button.

08-beaconupload

  1. Either drag and drop your CSV file into the appropriate area, or click into the window and browse to the saved CSV file.
  2. If the CSV upload is successful, a green checkmark will appear.

09-uploadbeaconsuccess

  1. If an upload is unsuccessful, a red X will appear. Please contact Smartwhere Support, including the CSV file, for assistance.

10-uploadbeaconfail

Yes No Suggest edit
Last updated on February 17, 2016

Wi-Fi

You can use Wi-Fi Networks as a Proximity Technology within your campaigns, and Wi-Fi Networks relevant to your campaigns may be added to your account from the Wi-Fi Networks section. Once a Wi-Fi Network is added and associated with a Group, you can add it to an Event and trigger notifications when users enter into range of your Wi-Fi Network, when they dwell within your Wi-Fi Network, or when they exit your Wi-Fi Network’s coverage range. Connecting or disconnecting from the Wi-Fi network may also be used to trigger notifications.

NOTE: Notifications based on Wi-Fi triggers are only available on the Android platform. This is a limitation of the iOS platform and apps made available through the iTunes Store.

 


Yes No Suggest edit
Last updated on February 16, 2016

Managing Wi-Fi Networks

To manage the Wi-Fi Networks in your account:

  1. Click on the Deployment tab
  2. In the sidebar, expand the Wireless Triggers section
  3. Click the Wi-Fi Networks link

01-wirelesstriggerlist

The Wi-Fi Network table displays the Wi-Fi Networks and the following settings in your account:

SSID: The Service Set Identifier (SSID), is the name of the Wi-Fi Network you wish to use as a Proximity technology

Validate BSSID: Yes/No option to validate the Basic Service Set Identifier of the router or LAN device. You set this toggle when adding your Wi-Fi Network.

Access: Yes/No option to allow connection to the SSID. You set this toggle when adding your Wi-Fi Network.

Security: The security protocol used for that network.

Passphrase: The password for the SSID.

Priority: The priority value for this Wi-Fi Network relative to other Wi-Fi Networks in this account.

BleScan: Yes/No toggle that enables scanning for BLE Beacons inside that Wi-Fi Network

Dwell: The time (in seconds) a user needs to be inside the Wi-Fi Network to trigger a Dwell-based Event.

Group: The Group the Wi-Fi Network is assigned to.

Navigating the Wi-Fi Networks Table

To pin this table to the Dashboard, click the Pin button in the Widget Heading Bar. pinned

A table or widget that has successfully been pinned will appear like this: unpinned

To unpin, re-click the Pin button.

The columns in this table can be sorted by clicking on the headers. Each header also includes a searchable text field to filter for specific items.  

In the upper left, you can change the number of entries displayed. If you have more Wi-Fi Networks than number of entries displayed, you can use the Previous and Next buttons in the lower right to navigate in between pages.

Exporting Table Contents

Clicking the Copy button allows you to copy your Wi-Fi Networks to paste into a different document.

Clicking the CSV, Excel or PDF buttons allows you to save a document locally as that file type.

Clicking the Print button provides a Print Preview version of the table.  Clicking the “ESC” key will return you to the Administrator.

03-printwireless

Yes No Suggest edit
Last updated on February 16, 2016

Adding or Editing Wi-Fi Networks

To add a new Wi-Fi Network, click on Wireless Triggers, then Wi-Fi Networks in the left-hand sidebar. Then, click the Add button above the Wi-Fi Networks table. To edit the settings for an existing Wi-Fi Network, click on the Wi-Fi Network (SSID) Name in the table.

Wi-Fi Network settings

04-wirelesssettings

In the Edit Wi-Fi Network widget, you’ll see the following settings:

SSID (Required): The Service Set Identifier (SSID), is the name of the Wi-Fi Network you wish to use as a Proximity technology. Enter the Wi-Fi Network’s SSID in this text field.

Validate BSSID: The BSSID (Basic Service Set Identifier) is a unique, non-editable property of the router or LAN device. Turn this toggle On to allow validation of the BSSID while using the Wi-Fi Network as the proximity technology. This helps ensure that it will prevent clients from receiving a signal from an access point trying to spoof your SSID. This is not currently in use, so the toggle should be left in its default setting.

Access: When toggled On, your customers will automatically be connected to the Wi-Fi network using the passphrase entered below.

Security: This is a drop-down menu for the security protocol on the Wi-Fi Network and is used in conjunction with the Access toggle. Options are None or WPA/WPA2.

Passphrase: This is the passphrase used to connect to the Wi-Fi network.  It is required to enable access to the network.

BLE Scan: This toggle prompts the Android client SDK to scan for known BLE Beacons while inside the Wi-Fi Network.

NOTE: Our general recommendation is to enable BLE Scan within the Wi-Fi Network range by setting the toggle to On, as limiting scans for Beacons until a device is within range helps to reduce battery consumption.

Dwell: This refers to the amount of time (in seconds) a user must be within range of the Wi-Fi Network before a Dwell-based Event is triggered.

Group: Select the Group to which this beacon will be associated from the drop-down list. If you do not have any Groups created, you can leave this selection blank, but in order to use this Wi-Fi Network with your campaigns, you will need to associate a Group. Please visit the Groups page for further content around Groups.

Once these fields have been configured, click Update.

NOTE: If there are issues with a required field, you will not be able to Update the settings until you resolve the issue.

Yes No Suggest edit
Last updated on February 16, 2016

Variables

You can add optional Variables to your Wi-Fi Networks.

Variables can be used like meta-tags to track interactions or pass along tracking information to assist with reporting usage and transactions with your Wi-Fi Networks.

04-variables

Attribute is a free text field for a unique identifier of a group of data.

Value is a free text field for the actual data in that group.

Once you’ve added an Attribute and Value, click the Add button to save.

Yes No Suggest edit
Last updated on February 16, 2016

Recent Transitions

The Recent Transition widget displays the ten most recent transitions against this Wi-Fi Network. The widget shows the type of transition (Enter, Dwell, Exit, Connect and Disconnect), the device and the timestamp when the transition occurred.

05b-wifirecent

Yes No Suggest edit
Last updated on February 16, 2016

Traffic

The Traffic widget lists all traffic against this Wi-Fi Network (Wi-Fi Enter, Wi-Fi Dwell, Wi-Fi Exit, Wi-Fi Connect and Wi-Fi Disconnect). This differs from the Traffic widget on the Analytics > Triggers page, which shows all traffic on your proximity technologies.

From this table, you can sort and filter on device ID, Source (or Transition type), Platform, Version (referring to the device’s OS version), and Age (the number of days since the traffic record was created). You can also search within the columns using the search box at the top of the table.

The columns in this table can be sorted by clicking on the headers. Each header also includes a searchable text field to filter for specific items.

In the upper left, you can change the number of entries displayed. If you have more Tag IDs than number of entries displayed, you can use the Previous and Next buttons in the lower right to navigate in between pages.

To drill down into a specific device, click on the Device ID. Please see the Devices section for more.

05a-wifitraffic

Yes No Suggest edit
Last updated on February 16, 2016

Events

The Event widget shows all scheduled Events. For more information, please visit the Events page.

Yes No Suggest edit
Last updated on February 16, 2016

Deleting a Wi-Fi Network

To delete a Wi-Fi Network, click into the Edit Wi-Fi Network widget for the Wi-Fi Network you’d like to delete from the table, and click the Delete button in the upper-right hand corner of the widget.

05-delete

A confirmation box appears, asking you to confirm the action. Click OK to confirm the deletion.

06-deletewireless

CAUTION: The Delete action is irreversible and any usage (traffic, transition) data will be lost.

Yes No Suggest edit
Last updated on February 16, 2016

Adding Multiple Wi-Fi Networks Using Bulk Upload

To add multiple Wi-Fi Networks at once, create a CSV file with the Wi-Fi Network settings and upload to your account using the Upload button.

Headers for bulk upload

In a CSV file, use the following headers (note the use of lower-case in the headers). For detailed information about the fields, please see the Wi-Fi Network Settings section above.

ssid

validate_bssid: “1” (for yes) or “0” (for no).

access: “1” (for yes) or “0” (for no).

security: “1” (for WPA/WPA2) or “0” (for none).

passphrase 

priority: This feature is intended to help prioritize the Wi-Fi Network to use. Leaving the value as “0” is recommended.

blescan: “1” (on) or “0” (off).

dwell (seconds)

group_id: The Group ID you wish to associate this Wi-Fi Network to. To find the Group ID, go to the Deployment tab, click Groups in the left sidebar. In the Groups widget, the left most column will provide the Group ID.

NOTE: If you enter in a Group ID that is not in your account, the CSV upload will fail.

Uploading your CSV

  1. Once you’ve populated your CSV, save it as a CSV file.
  2. Click the Upload button.

07-wirelessupload

  1. Either drag and drop your CSV file into the appropriate area, or click into the window and browse to the saved CSV file.
  2. If the CSV upload is successful, a green checkmark will appear.

08-wirelessuploadsuccess

  1. If the upload is unsuccessful, a red X will appear. If your upload is unsuccessful, please contact Smartwhere Support, including the CSV file, for assistance.

09-wirelessuploadfail

Yes No Suggest edit
Last updated on February 16, 2016

Touch/Scan Triggers

Touch and Scan refers to the action needed to use Near Field Communication (NFC) Tags and Quick Response (QR) Codes. NFC is supported by Android devices, but iOS devices do not support NFC outside of payment based functionality at this time. QR requires a barcode reader to decipher the code.

Encoding Tags

Encoding an NFC Tag generates a Tag ID, which also includes a QR Code that performs the same action as the NFC Tag. Thus, for the purposes of this guide, Tag ID refers to both the NFC Tag and the corresponding QR Code.

NOTE: While the other Proximity Technology tables (such as Geofence, Beacon and Wi-Fi Networks) allow the creation of new items, new Tags may only be added to your account after following the steps in the Encoding NFC Tags and QR Codes article.

Info

The Info widget shows the associated QR Code for this Tag as well as the date the Tag was created, and the number of interactions by type (Tap, Scan).

11-taginfo

ID and UID are unique identifiers for the Tag,

Created is the date the Tag was created.

Taps represents the number of times the Tag was tapped by an NFC enabled device.

Scans represents the number of times the QR code was scanned

QR is the QR code associated with the Tag ID.

 


Yes No Suggest edit
Last updated on February 16, 2016

Managing Your Tags

  1. Click on the Deployment tab
  2. In the left sidebar, click on Touch/Scan Triggers

01-touchtriggertable

The Tag settings table displays the Tags and the following settings in your account:

Code: This is the assigned ID for your NFC Tag or QR Code.  This is generated by the administrator automatically.

Name: This is the name of your tag.  You can set this on the Edit Tag Settings screen.

Action: This is the action assigned to the tag ID.

NOTE: The Action listed here shows the Action on the Tag. If the Tag is assigned to a Group and the Group is locked, the Group Action will not be shown on this table.

Taps: This shows the number of Taps (using NFC) on this Tag ID.

Scans: This shows the number of Scans (using a QR reader) on this Tag ID.

Group: This shows the assigned Group, if applicable.

Navigating the Tags Table

To pin this table to the Dashboard, click the Pin button in the Widget Heading Bar. pinned

A table or widget that has successfully been pinned will appear like this: unpinned

To unpin, re-click the Pin button.

The columns in this table can be sorted by clicking on the headers.  Each header also includes a searchable text field to filter for specific items.

In the upper left, you can change the number of entries displayed.  If you have more Tag IDs than number of entries displayed, you can use the Previous and Next buttons in the lower right to navigate in between pages.

Exporting Table Contents

Clicking the Copy button allows you to copy your Tag IDs to paste into a different document.

02-touchtriggercopy

Clicking the CSV, Excel or PDF buttons allows you to save a document locally as that file type.

Clicking the Print button provides a Print Preview version of the table. Clicking the “ESC” key will return you to the Administrator.

Yes No Suggest edit
Last updated on February 18, 2016

Export Tags

Generate a report of all of the Tags in your account by clicking the Export Tags button on the Tags Table.

04-tagexport

Tag Export Report settings

Destination Email (Required): The default value is the email address of the account owner, but the report recipient address can be changed.

Customer: Displays the name of the account owner (not editable).

Group: Select from the drop-down to filter the report for information regarding a specific group, or all in the account.

Description: If you would like to save the parameters of this report, this field will be displayed in the description column in the  Saved Report widget.

Click Save Button: to save your parameters. This will also save your report to the Saved Reports widget.

Click Run Report to run this report, and email to the email address specified in the Destination Email field.

Yes No Suggest edit
Last updated on February 16, 2016

Bulk Operations

Select your Tags and change their assigned Actions, Group, or Variables using the Bulk Operations button.

05-tagbulk

Selection Criteria

You can filter and search for specific tags in the Selection Criteria widget using the following fields:

Name: Allows a search for the Name associated to the Tag

Location: Allows a search for the Location of the Tag

Taps: Allows a search for a min and max on number of Taps on the Tag

Scans: Allows for a search for a min and max on number of Scans on the Tag

Action: Drop-down menu allowing a filter on the Group the Tags are currently assigned to

Created: Allows for a filter on the Created Date on the Tag

Variables: Allows for a search on any Variables on the Tag

Once you’ve filled in the search and filter criteria, click the Filter button to execute.

Selected Tags

Tags filtered using the Selection Criteria appear in the Selected Tags widget.

The columns in this table can be sorted by clicking on the headers. Each header also includes a searchable text field to filter for specific items.

In the upper left, you can change the number of entries displayed. If you have more Tags than number of entries displayed, you can use the Previous and Next buttons in the lower right to navigate in between pages.

Update Data

Make bulk changes to the Action, Group or Variables of your Selected Tags from the Update Data widget.

06-tagupdatedata

Action: Drop-down menu that presents the possible Actions.

Group: Drop-down menu that displays the other Groups to which you can assign Tags.

Variables: An optional Name and Value Pair.

Once you’ve selected the Data to change, click the Update button. The following confirmation dialog will appear.

07-tagupdateconfirm

Yes No Suggest edit
Last updated on February 16, 2016

Editing Tag Settings

To edit the settings for an existing Tag, click on the Tag Name in the table. Tip: If you don’t see the Tag listed, or you’d like to add a new Tag, please follow the instructions in the Encoding NFC Tags and QR Codes article.

08-edittagsettings

Tag settings

In the Edit Tag widget, you’ll see the following settings:

Name: Use this field to associate a name to your NFC Tag/QR Code. This Tag Name is not visible to the end user.

Latitude/Longitude/Address: These fields can be filled in to designate the location of the NFC Tag/QR Code. Note: This is required if you’d like to enable tracking of interaction via the Real Time Monitor. Additionally, if the Tag is part of a Group and the Group is set to Smart Location, an end user’s interaction with the Tag can update the Tag’s latitude and longitude value in the Administrator automatically, if the location shared is more accurate than the previously reported Latitude and Longitude.

Location/Timezone: This field will update based on the location information entered above, and cannot be entered manually.

Group: Select the Group to which this Tag will be associated from the drop-down list. If you do not have any Groups created, you can leave this selection blank, but in order to use this Tag with a campaign, you will need to associate a Group. Please visit the Groups page for further content around Groups.

Yes No Suggest edit
Last updated on February 16, 2016

Action

You can determine a Tag’s Action, or what will happen when a user interacts with a Tag from the Action widget.

09-tagaction

Action widget settings

In the Action widget, you’ll be able to set Action and other settings for this Tag. Note: You can set Actions at the Event, Group and Tag level. Tag Actions set at the Tag-level  will be used only if the Group the Tag is associated to is unlocked and the Group’s Action is not recognized. For example, if you want all of your Tags to perform the same action, you can assign all of your Tags in the same Group, make sure the Group is Locked and specify the action on the Action tab of the Group.  Alternatively, if you want each Tag to perform a different action, you can either Unlock the Group or un-assign the Tag from the Group to manage the Tags individually.

If you’ve made changes to Actions associated with the individual Tag, click the Update button to save changes made to the Tag and the Action.

For a description of the hierarchy of actions at the Event, Group and Tag levels, please read the Default action hierarchy section.

Default action hierarchy

Actions may be set at the Event, Group and Tag level. The Action that’s taken for NFC Tags and QR Codes in a Group is determined by the following hierarchy:

Event: For Tags in a Group, the Action based on an Event supersedes all other actions.

Example: I have an Event with a QR Scan as the trigger. The Event has a Twitter Action. This means that even though the Group has an Action of URL Redirect, and the QR Code has an Action of a YouTube video, the Event-level Action supersedes, and the end-user will go to Twitter upon scanning the QR code.

Group: If the Tag’s Group is Locked, the Action on the Group supersedes any Actions set at the individual Tag level. Tag: If the Tag’s Group is unlocked, and each tag has it’s own separate Action, the Group’s Action is not recognized and the Actions encoded on the individual Tag will take effect.

The list of Actions available is listed on the Content page.

Yes No Suggest edit
Last updated on February 16, 2016

Recent Engagements

The Recent Engagement widget displays the ten most recent taps/scans against this Tag ID.  The widget shows the action performed, the device OS and ID and the timestamp of the tap/scan.

10-tagengagement

Yes No Suggest edit
Last updated on February 16, 2016

Info

The Info widget shows the associated QR Code for this Tag as well as the date the Tag was created, and the number of interactions by type (Tap, Scan).

11-taginfo

ID and UID are unique identifiers for the Tag,

Created is the date the Tag was created.

Taps represents the number of times the Tag was tapped by an NFC enabled device.

Scans represents the number of times the QR code was scanned

QR is the QR code associated with the Tag ID.

Yes No Suggest edit
Last updated on February 16, 2016

Variables

You can add optional Variables to your Tag IDs.

Variables can be used like meta-tags to track interactions or pass along tracking information to assist with reporting usage and transactions with your Tag IDs.

12-variables

Attribute is a free text field for a unique identifier of a group of data.

Value is a free text field for the actual data in that group.

Once you’ve added an Attribute and Value, click the Add button to save.

Yes No Suggest edit
Last updated on February 16, 2016

Traffic

The Traffic widget lists all traffic against this Tag ID. This differs from the Traffic widget on the Analytics > Triggers page, which shows all traffic on your proximity technologies.

From this table, you can sort and filter on device ID, Source, Platform, Version (referring to the device’s OS version), and Age (the number of days since the traffic record was created). You can also search within the columns using the search box at the top of the table.

The columns in this table can be sorted by clicking on the headers. Each header also includes a searchable text field to filter for specific items.

In the upper left, you can change the number of entries displayed. If you have more Tag IDs than number of entries displayed, you can use the Previous and Next buttons in the lower right to navigate in between pages.

To drill down into a specific device, click on the Device ID. Please see the Devices section for more.

10a-tagtraffic

Yes No Suggest edit
Last updated on February 16, 2016

Trigger Map

The Trigger Map displays the location of all of your proximity technologies in action.

01 - triggermap

This map can be used to provide an overlay of all of your deployed proximity technologies, which can help identify heavy traffic or reveal any areas where you are missing coverage.

04 - triggermapzoomedin

The map can be filtered to display all items, or selected items by clicking the Toggle buttons along the top.

Toggle Geofence displays or hides active Geofences.

Toggle Beacons displays  or hides active Beacons.

Toggle Tags displays or hides active Tags.

NOTE: Tags that do not have a latitude and longitude assigned will default to a latitude and longitude of 0.00, 0.00, hence the NFC pin just below Ghana in the Trigger Map screenshot above.

Toggle Heatmap displays or hides activity on the proximity technology. As more traffic occurs, the red color of the indicator on the map intensifies.  

Clustering is a drop-down menu that allows you to change how the location pins are displayed.

No Clustering displays all of the proximity technology pins on the map.

Market Cluster groups nearby pins together and provides a numeric value for the number of items in the group.

02 - triggermapmarkercluster

Spider Cluster displays a single pin that, when clicked, will expand to display all pins.

03 - triggermapspidercluster

Custom Data is a drop-down list allowing you to view the locations of various stores and chains gathered from a point of interest database.

You can zoom in and zoom out of the map using the controls in the lower right corner in the widget. Clicking the map and dragging will allow you to move the map around.

Clicking a location pin displays the specific Proximity Technology, whether it’s a Beacon, Geofence, or Tag ID (Wi-Fi Networks are not available on this map as Wi-Fi Networks do not capture the latitude and longitude when they’re added to the Web Administrator).

Yes No Suggest edit
Last updated on February 19, 2016

Admin

From the Admin tab, you can manage your users and configure system settings.


Yes No Suggest edit
Last updated on February 2, 2016

Manage Users

The Manage User section lets you add, modify or delete user accounts that have access to your system.

01-userslist

This section contains a paginated list of all users associated with the account. You can sort either on descending or ascending order based on any column by clicking the column header. You can move between the results by clicking the Previous or Next buttons or by clicking the specific page number, or change the number of results displayed per page by clicking the results drop-down menu. You can also filter results by entering text in the Search field.


Yes No Suggest edit
Last updated on February 17, 2016

Adding New Users

Additional users can be added by clicking the New button which will open the User Manager section.

02-edituser (1)

Tip: Work in each widget separately.  Add the new user’s email and password, their first and last name, then click Update.  From the Manager User widget click back into the user, then configure their Roles and click Update.  Repeat for the Permissions widget as well.

Yes No Suggest edit
Last updated on February 19, 2016

Edit User

The Edit User widget contains the following fields:

Email: Enter the user’s email address. They will use this email to log into the system.

First Name: Enter the user’s first name.

Last Name: Enter the user’s last name.

Telephone: Enter the user’s phone number.

Password: Enter the password for the user.  When editing an existing user’s settings, you can update their password from this screen in case they lose their password.  If you, as the administrator, lose your password, please contact support@smartwhere.com for a password reset.

Verify Password: Enter the same password entered in the Password field to confirm password selection.

Tip: When creating an account for a user, ensure that user logs in and updates their password using a combination of letters, numbers and symbols.

03-userpassword

Once changes have been made to user settings, click the Update button.

Yes No Suggest edit
Last updated on February 17, 2016

Roles

The Roles widget lets you select which pre-defined roles in which the user is a member. Each role is a collection of permissions. The system includes both built-in roles and allows you to create your own custom roles.

To make the user a member of a role, click the Member radio button. To remove a user from a role click the Not Member radio button.

04-roles (1)

The default available roles are:

Administrators: An Administrator role will enable access to the Admin Tab.

Analytics Read: Analytics Read role provides read-only access to the Analytics Tab.

Analytics Write: Analytics Write role provides write access to the Analytics Tab. In order for the Analytics Tab to be visible, the user must have Analytics Read access as well.

Campaign Read: Campaign Read role provides read-only access to the Campaign Tab.

Campaign Write: Campaign Write role provides write access to the Campaign Tab. In order for the Campaign Tab to be visible, the user must have Campaign Read access as well.

Content Read: Content Read role provides read-only access to the Content Tab.

Content Write: Content Write role provides write access to the Content Tab. In order for the Content Tab to be visible, the user must have Content Read access as well.

Deployment Read: Deployment Read role provides read-only access to the Deployment Tab.

Deployment Write: Deployment Write role provides write access to the Deployment Tab. In order for the Deployment Tab to be visible, the user must have Deployment Read access as well.

test super user: Superuser roles provides limited access to the Admin Tab.  

Once changes have been made to user roles, click the Update button.

Yes No Suggest edit
Last updated on February 24, 2016

Permissions

The Permissions widget allows you to set specific permissions for the user. The permissions set at the user level override permissions inherited from Role membership. Each permission can be set to one of three values:

Allow: Grants permissions to access

Deny: Removes permissions to access

Inherit: Uses access provided at the Role level to allow/deny access

05-permissions (1)

The available permissions are:

Access Admin: Determines whether the user can access the Admin Tab

Analytics Read: Determines whether the user can access the Analytics Tab with read-only rights.

Analytics Write: Determines whether the user can access the Analytics Tab with read and write permissions.

Campaign Read: Determines whether the user can access the Campaign Tab with read-only rights.

Campaign Write: Determines whether the user can access the Campaign Tab with read and write permissions.

Content Read: Determines whether the user can access the Content Tab with read-only permissions.

Content Write: Determines whether the user can access the Content Tab with read and write permissions.

Deployment Read: Determines whether the user can access the Deployment Tab with read-only permissions.

Deployment Write: Determines whether the user can access the Deployment Tab with read and write permissions.

Manage Account: Determines whether the user can access the Manage Users, Manager Roles and Manage Permissions sections of the Admin Tab.

Once changes have been made to user permissions, click the Update button.

Yes No Suggest edit
Last updated on February 19, 2016

Deleting Users

To delete an existing user, click on the user in the Manage Users section. From the User Manager settings, click the Delete button. A confirmation dialog will appear asking you to confirm your choice.

07-deleteuserconfirm

Click the OK button confirm your selection and delete the user.

Note: You must have the Manage Account permission to delete a user and that you cannot delete the account you are currently logged in with.

Yes No Suggest edit
Last updated on February 17, 2016

Audit Trail

The Audit Trail table provides a historical view of changes and updates made to the account.

01-auditlogtable

ID: System generated identification number of the activity

Timestamp: The time and date when the activity was completed

User: The user who performed the activity

Resource: The section where the activity took place.

Audit Type: The type of activity completed (Add, Delete, Modify)

Attributes: The fields that were updated

Data: The content added, modified or deleted.

This table contains a paginated list of all changes made to the Smartwhere Administrator. You can sort either on descending or ascending order based on any column by clicking the column header. You can move between the results by clicking the Previous or Next buttons or by clicking the specific page number, or change the number of results displayed per page by clicking the results drop-down menu. You can also filter results by entering text in the Search field.

Clicking the Copy button allows you to copy the data displayed in the Audit Trail table to paste into a document.

The CSV, Excel and PDF buttons allows you to export and save the data in the table to the file type of your choice.  

The Print button gives a printer friendly view of the data in the table.

Clicking on a row in the table expands the Audit Detail view, which gives an expanded view into the activity and the change made.  

02-auditdetail

 

Yes No Suggest edit
Last updated on February 19, 2016

Account Information

The Account Information section lets you view and edit information related to your system wide account as well as provide access to your account specific database.


Yes No Suggest edit
Last updated on February 16, 2016

Edit Account

View and edit information related to the currently logged in user account using the Edit Account widget.
01-editaccount

This widget includes the following fields:

First Name: (Required) The user’s first name.

Last Name: The user’s last name.

Email: (Required) The user’s email address. They will use this email to log into the system.

Telephone: The user’s phone number.

Fax: The user’s fax number.

Password: (Required) The password for the user.

Verify Password: (Required) The same password entered in the Password field to confirm password selection.

Timezone: A drop-down menu that displays the timezone for the user account. This defaults to America / Los Angeles.

Note: Changing the Timezone for a user will change the timestamp on traffic and transition data displayed in the Administrator.

Click the Update button to save any changes to the account.

Yes No Suggest edit
Last updated on February 17, 2016

Account Information

The Account Information widget displays information about your specific account limitations.

02-accountinfo

The displayed fields are:

Account Type: The specific account type for the system. The default value is Basic.

Groups: The current total number of groups for this account.

Max Groups: The maximum number of groups allowed for this account.

Tags: The current total number of tags for this account.

Max Tags: The maximum number of tags allowed for this account.

Yes No Suggest edit
Last updated on February 17, 2016

Developer Information

The Developer Information widget provides information for your specific API Key and Secret. Both unique values are required by the Smartwhere mobile SDK client to function properly.

03-developerinfo

For more information on configuring the Smartwhere mobile SDK client please see the iOS and Android Integration guides.

Yes No Suggest edit
Last updated on February 17, 2016

Customer Database

Each Smartwhere account includes it’s own database instance. You may use this database to store any custom information you wish and the information is easily available directly to your proximity enabled applications.

04-customerdb

The Customer Database widget provides host and credential information to access your unique database as well as a link to a Database Administrator web utility. The widget will display the following fields:

Server: The host address of your unique customer database.

Database: The unique name of your customer database.

User Id: The user ID required to access your customer database.

Password: The unique password required to access your customer database.

Click the Launch DB Administrator button to launch the web-based Database Administrator utility in another window.

The account details displayed in the Customer Database widget is the information you will need to access your user DBs.  Click the Login in button to proceed.  

04a-dblogin

Yes No Suggest edit
Last updated on February 19, 2016

File Manager

The Your Files widget links to the File Manager, which you can use to call up saved CSS files, images, and javascript files, or add new files and directories. To store files in File Manager, simply drag and drop your files into the desired directory, or select the file by navigating through the appropriate folders on your computer.

01-filedirectory

For example, you want to save an image of your company’s logo in order to include it on your Interstitials.

  1. Either Drag and Drop the image file or click on the “Drop files to upload” area
  2. Once the image has uploaded, it will appear in the directory to the left. Clicking on the image provides the static URL of the image02-fileupload
  3. When creating your interstitials, you can reference that URL through <a href> tag to display the image.

To delete the file, click the Delete button.

Caution: Deleting the file in this widget does not provide a warning dialog.  If you delete the file in error, you will need to re-upload the file.


Yes No Suggest edit
Last updated on February 2, 2016

Application IDs

Manage the Application IDs created for your account in the Application IDs section. Application IDs are necessary for proper beacon setup.

On iOS devices, as iOS devices will not scan for beacon UUIDs without knowing which UUID to scan for, the Application ID enables you to associate the Beacon UUID with an application ID so that customers on iOS devices can receive beacon-based notifications.

For Android, you can enable Beacon scanning within a Geofence or Wi-Fi Network, or you can enable BLE Scanning in the Application ID widget.

01-appidlist

The columns in this table can be sorted by clicking on the headers. You can also search using the search text field.  

The table shows 10 entries.  If you have more than 10 Application IDs, you can navigate in between the pages by clicking the Previous and Next buttons, or clicking on the page number in the lower right of the table.  

Clicking the Copy button allows you to copy your Application IDs to paste into a different document.

Clicking the CSV, Excel or PDF buttons allows you to save a document locally as that file type.

02-saveappids

Clicking the Print button provides a Print Preview version of the table.  Clicking the “ESC” key will return you to the Administrator.

03-printappids


Yes No Suggest edit
Last updated on February 16, 2016

Adding or Editing Application IDs

If you’ve created a Application ID through the Account Information page (above), your App ID should be visible in the Application ID’s widget. Simply click on that Application ID to be taken into the Edit Application view.

If you have not created an Application ID, or to create a separate Application ID, click the New button in the upper right.

04-newappid

In the Edit Application Widget

ID is the system generated number for your Application ID

BLE Scan toggle allows BLE Scanning on Android without requiring a Geofence or Wi-Fi Network with BLE Scanning enabled.

Caution: Enabling BLE Scan at the Application ID may impact device battery.

Description is the name of your Application ID.

Click the Update button to save.

In the Assigned UUID’s widget, you can associate Beacon UUIDs to your Application ID. This is a requirement for iOS devices. Use the drop-down menu to select the Beacon UUIDs you’ve entered in the Beacon section and click the add button.

If you change your Beacon UUIDs, or no longer use a specific Beacon, you can remove the Beacon UUID to Application ID assignment by clicking the X button.

Yes No Suggest edit
Last updated on February 17, 2016

Deleting Application IDs

To delete an Application ID, click the Delete button in the upper right in the Edit Application view.  

A confirmation box appears, asking you to confirm the deletion.  Click OK to proceed

05-deleteappidconfirm

Caution: The Delete option is irreversible.

Yes No Suggest edit
Last updated on February 17, 2016

Android Client SDK Integration Guide

This document is written using Android Studio as the development platform. It includes basic instructions in the Appendix (link to appendix) to link the Smartwhere library in Eclipse.  If you require further assistance integrating the Smartwhere SDK into your application in Eclipse, please contact our support team at support@smartwhere.com.


Yes No Suggest edit
Last updated on February 2, 2016

Release Notes

Build 17258 (proximity_sdk-smartwhere-release_17258)

  • Added the ability for events to be removed from the notification tray when exiting from the proximity
  • Added the ability for delayed events to start the delay when the application is backgrounded
  • Created ProximityLifecycleCallbacks class for internal management of lifecycle events
  • Added the ability to replace portions or all of the event notification title and text using client side user or tracking attributes
  • Remove dependency on google play services with runtime check to enable features that require google play services
  • Added methods to ProximityControl to set and get locale
  • BUG FIX: fixed miscellaneous minor bugs

Build 17194.1 (proximity_sdk-smartwhere-release_17194.1)

  • Remove allowBackups manifest entry

Build 17194 (proximity_sdk-smartwhere-release_17194)

  • Modified to remain dormant until server contact is made
  • Remove dependency on permissions and google play service location
  • Refactor to support back to API 9
  • Implement processMappedEvent and add cancelScanAsNotification
  • Add PROXIMITY_NOTIFICATION_ICON_NAME configuration
  • Add ttl_minutes to discovery calls and use instead of global if exist
  • Create tune flavor – Remove some permissions from manifest
  • Remove Install_referrer intent filter

Build 17087.1 (proximity_sdk-smartwhere-release_17087.1)

  • Remove Install Referrer Intent-filter

Build 17087 (proximity_sdk-smartwhere-release_17087)

  • Improve geofence point in polygon algorithm
  • Add area scan conditions -AREA_SCAN_BATTERY_THRESHOLD, AREA_SCAN_TRANSMISSION_WIFI_ONLY
  • Enable runtime configuration via adb
  • Added exit strategy field to geo fences – EXIT_STRATEGY_POLYGON, EXIT_STRATEGY_RADIUS

Build 16364.2 (proximity_sdk-smartwhere-release_16364.2)

  • BUG FIX: Fixed issue where small fences don’t exit properly when ranging is disabled
  • BUG FIX: Fixed issue with proximity control overwriting server configs

Build 16364.1 (proximity_sdk-smartwhere-release_16364.1)

  • Modify proximity control to set configuration directly instead of via proximity activity
  • BUG FIX: Fix crash on break down when google api is not connected.

Build 16364 (proximity_sdk-smartwhere-release_16364)

  • Implement fused location api
  • Modify the server override logic to persist the values
  • Changed wifi enter/exit threshold RSSI values
  • Change the install referrer filter to have priority -1
  • Added configuration for DEBUG_LEVEL
  • Various bug fixes

Build 16158 (proximity_sdk-smartwhere-release_16158)

  • Built with API 23 and Google Play Service (Location) 8.4.0
  • Support Android 6 permission model.
    • Add permission dialog to proximity activity
    • Added a hook for providing custom permission activity
    • Add configuration to disable permission requests for proximity.  This allows the application to handle all permission requests.
  • Remove some deprecated communication APIs.

Build 16124 (proximity_sdk-smartwhere-release_16124)

  • Added visit ID and duration to tracking
  • Added device conditions – DeviceSecondsSinceInstall, DeviceSecondsSinceUpdate, DeviceSDKVersion
  • Persist Geofence, Beacon, and WifiNetwork lists across restarts.
  • BUG FIX: Catch runtime exceptions in get application beacons call.
  • BUG FIX: Fix incorrect beacon filter length.

Build 16060 (proximity_sdk-smartwhere-release_16060)

  • Refactored the Attribute api and persist the data across restarts
    • note: This change will require small code changes to applications that use this api.
  • Refactored the TrackingAttribute api and persist the data across restarts
    • note: This change will require small code changes to applications that use this api.

Build 16055 (proximity_sdk-smartwhere-release_16055)

  • Added support for server side client overrides
  • Added support for the silent notification type
  • Added support for BLE scanning filter type to geofences and wifi networks

Build 16015 (proximity_sdk-smartwhere-release_16015)

  • Added support for client SDK event scheduling
  • Added support for event data tracking on event object
  • Added support for addition of event variables to the event class
  • Added BLE Scanning on Android 5.0+

Build 15351 (proximity_sdk-smartwhere-release_15351)

  • Enabled support for Google Play Services version 8.3.0
  • BUG FIX: Addressed an issue with clearing cache when service stops
  • Exposed ProximityConfiguration read variables including getting event and proximity objects

Build 15334 (proximity_sdk-smartwhere-release_15334)

  • Improved tracking queue processing
  • Added support for Application ID tracking
  • Added support for app start tracking

Build 15295 HF1 (proximity_sdk-smartwhere-release_15295_hf1)

  • BUG FIX: Fixed an issue with a null scan result from Wi-Fi
  • Added timestamp to tracking
  • Added support for Google Advertiser ID tracking

Build 15295 (proximity_sdk-smartwhere-release_15295)

  • BUG FIX: Addressed an issue preventing the service from stopping properly

Build 15292 (proximity_sdk-smartwhere-release_15292)

  • BUG FIX: Addressed an issue removing deleted events.
  • Addressed an issue where beacon list did not update correctly when a beacon id was set to 0

Build 15273 (proximity_sdk-smartwhere-release_15273)

Yes No Suggest edit
Last updated on September 18, 2017

Requirements

Android Studio

Android Studio is now the official IDE for Android (http://developer.android.com/sdk/index.html). We recommend using Android Studio version 1.5.1 or higher to integrate the Smartwhere SDK with your application.

Minimum Android SDK Target

The SDK requires a minimum Android SDK of 18 (Android 4.3 Jelly Bean) and the maximum target SDK is currently 22.  If you are developing for Android M, please contact our support team.

minSdkVersion 18
targetSdkVersion 22

Google Play Location Services

The Smartwhere Android client SDK uses Google Play Services version 8.3.0. Only the location package of Google Play Services API (com.google.android.gms.location) is required for the client.

Please reference https://developers.google.com/android/guides/setup for more information on integrating Google Play Services within your app.


Yes No Suggest edit
Last updated on January 29, 2016

Project Configuration for Android Studio

Include the Smartwhere SDK library

To include the Smartwhere Android client SDK library within your app copy the AAR file (example: “proximity_sdk-smartwhere-release.xxversionxx.aar”) from your file manager into the Project > apps > libs  subfolder in the Android Studio Project view, as shown below:

01-appdirectory

A confirmation dialog will appear after moving the file:

02-copy

Click the OK button to confirm your action. You should now see that the  Smartwhere  SDK has been added to your project.

Update your build.gradle file

Update the app build.gradle script to include the libs directory to your repositories and dependencies.  The libs  directory must be included  as a  flatDir within the  repository as shown in the following example.

repositories {
      mavenCentral()
      mavenLocal()
      flatDir {
            dirs 'libs'
      }
}

Add both the Google Play Location Services and Smartwhere library as compile dependencies by adding the following:

dependencies {
     compile fileTree(dir: 'libs', include: ['*.jar'])
     compile 'com.android.support:appcompat-v7:23.1.1'
     compile 'com.google.android.gms:play-services-location:8.3.0'
     compile name:'proximity_sdk-smartwhere-release.xxversionxx',ext:'aar'
 }

NOTE: The actual AAR file name you just dragged into the ‘libs’ folder will need to be matched in the ‘proximity_sdk-smartwhere.release-xxversionxx’ compile dependency.

Update your app manifest for NFC deep linking actions

NFC (Near Field Communication) tags are one of the proximity technologies supported by the Smartwhere platform. Like all proximity technologies, you can configure NFC tags to take specific actions when a proximity action, in this case physical tap, occurs.

One of the most common uses of NFC as a proximity technology is for app distribution. When a user taps a configured NFC tag, it can automatically load the appropriate app store to download the desired app.

By updating your app manifest to register for specific NFC actions you can have your app automatically deep link to the most contextually relevant action on any subsequent taps after the user has initially loaded your app. This is known as load and launch functionality.

To optionally have your app opened when a registered NFC tag is tapped, open your app’s manifest and add the following code to the application node:

<activity
    android:name="com.proximity.library.ProximityActivity"

    android:launchMode="singleTop" >
        <intent-filter>
           <action android:name="android.nfc.action.NDEF_DISCOVERED"/>
           <category android:name="android.intent.category.DEFAULT"/>
           <data android:scheme="http" android:host="ntag.co" android:pathPattern="/xxxxxx/.*" />
           <data android:scheme="http" android:host="www.ntag.co" android:pathPattern="/xxxxxx/.*" />
        </intent-filter>

 </activity>

In the example above, the “XXXXXX” needs to be replaced with your specific Application ID, which can be found in the Admin > Account Information > Application ID section of the Smartwhere Administrator. In addition, the NFC tags must have the application ID encoded into the tags via our High Speed NFC Encoding Platform. For more information please see High Speed Encoding.

Update the notification icon

By default, notifications generated by the Smartwhere SDK will use the following default Smartwhere icon.

03-sw-logo

To use your own notification icon, you can simply update it by including the appropriate image resource within your app with the name ic_notification in the Drawable folder.

For guidance on customizing your notification icons, the best resource is to refer to Google’s documentation http://developer.android.com/design/patterns/notifications.html.


Yes No Suggest edit
Last updated on February 2, 2016

Client Integration

Configure the client

The Smartwhere client includes a number of settings that allow you to balance the performance of the client relative to proximity responsiveness and battery consumption.

These settings are configured via static properties of a standard Java class named ProximityConfiguration located in the main java folder.

NOTE: If a property is not explicitly defined the default settings will apply.

For testing and development purposes, it is common to use aggressive values to see immediate results. However the default configuration values are the recommended production settings to optimize battery performance.

The following settings are available for configuration:

public static final String APPLICATION_ID
This is a property that defines your mobile application’s unique ID. This ID is used for associating both Beacons and NFC tags exclusively with your app. Your Application IDs are generated and managed from within the Smartwhere Administrator under the Admin > Account Management > Application ID section.

public static final String API_KEY
This is a property that sets your unique API key. Your API key is available from within the Admin > Account Information section of the Smartwhere administrator.

public static final String API_SECRET
This is a property that sets your unique API secret. Your API secret is available from within the Admin > Account Information section of the Smartwhere administrator.

public static final long GEOFENCE_UPDATE_TIME
This is a property that defines how often, in minutes, the client will ask the server for new geofences based on the client’s current location and update its local cache. By default, this is set to one hour. Decreasing the update time may affect app battery performance.

public static final long WIFI_UPDATE_TIME
This is a property that defines how often, in minutes, the client will ask the server for a list of known Wi-Fi networks and update its local cache. By default, this is set to one hour. Decreasing the update time may affect app battery performance.

public static final long BEACON_TTL
This is an optional property that defines the cache life from the time of engagement, in minutes, for a beacon. If the cache life is expired, the Smartwhere client will contact the server for updated information related to the beacon. By default, this is set to 60 minutes. Decreasing the frequency of the update time may affect app battery performance.

public static final long FENCE_TTL
This is an optional property that defines the cache life from the time of engagement, in minutes, for a fence. If the cache life is expired, the Smartwhere client will contact the server for updated information related to the fence. By default, this is set to 60 minutes. Decreasing the frequency of the update time may affect app battery performance.

NOTE: If you are using custom actions that utilize scripts in which the results are constantly dynamic you will need to set this value to 0, otherwise the client will potentially be served cached results.

public static final long TAG_TTL
This is an optional property that defines the cache life from the time of engagement, in minutes, for a tag. If the cache life is expired, the Smartwhere client will contact the server for updated information related to the tag. By default, this is set to 60 minutes. Decreasing the frequency of the update time may affect app battery performance.

NOTE: If you are using custom actions that utilize scripts in which the results are constantly dynamic you will need to set this value to 0, otherwise the client will potentially be served cached results.

public static final long WIFI_TTL
This is an optional property that defines the cache life from the time of engagement, in minutes, for a WiFi network. If the cache life is expired, the Smartwhere client will contact the server for updated information related to the WiFi network. By default, this is set to 60 minutes. Increasing the frequency of the update time may affect app battery performance.

NOTE: If you are using custom actions that utilize scripts in which the results are constantly dynamic you will need to set this value to 0, otherwise the client will potentially be served cached results.

public static final long BEACON_SCAN_INTERVAL
This is a property that defines how often, in seconds, the client will scan for nearby Beacons. By default, this is set to 15 seconds. Shortening the interval time may affect app battery performance.

public static final long BEACON_SCAN_DURATION
This is a property that defines the duration of time, in seconds, that the client will scan for nearby Beacons during a scan interval. By default, this is set to 2 seconds. Increasing the scan duration time may affect app battery performance.

public static final long LOCATION_UPDATE_TIME
By default, the Smartwhere client uses automatically generated location updates from the operating system to determine it’s current location. This is a property that defines how often, in minutes, that may pass without an operating system update before the Smartwhere client will force a location update. Note: More frequent forced location updates will impact battery performance. The default value of this property is 60 minutes.

public static final long NOTIFICATION_HANDLER_SERVICE
By default, when a proximity event occurs, the Smartwhere client will automatically create and dispatch an Android notification for the event. Alternatively, you can configure the Smartwhere client to pass any generated proximity notifications to the IntentService of your choice by setting this optional property to the receiving IntentService name. This property allows you to potentially pre-process any notifications before actually displaying them to the user. Please see the file ProximityNotificationService.java for an example of a custom notification handler service.

public static final long CUSTOM_ACTION_ACTIVITY
In addition to the built-in actions that you may execute when a proximity event is triggered, the Smartwhere platform also supports custom actions. These actions are scripted on the server and pre-processed before they are sent to the client. By default the Smartwhere client will generate and broadcast a local intent when a custom action is triggered.

Alternatively, you can send any generated custom actions directly to an activity of your choice using this optional property, passing in the name of the receiving activity. Please see the file DemoActivity.java for an example of a custom action receiving activity.

public static final boolean SERVICE_AUTO_START
This is a property that defines whether or not the proximity service will automatically start itself following a device cold boot, a user presence change, or a power event change. The default value is TRUE.

If you prefer to control the proximity service, you may wish to set this to FALSE and then use the ProximityControl.startService and ProximityControl.stopService methods. Additionally, you can programmatically set the SERVICE_AUTO_START property at runtime via the ServiceSettings.setServiceAutoStart method.

public static final boolean PAYLOAD_ENCRYPTED
This is an optional property that, when set to TRUE, determines whether the client will search for additional encrypted payload content that has been encoded directly to the NFC tag itself. Tags that include the additional payload, which only the client can decrypt and have been seeded based on the tags unique ID, can essentially prevent your tags from being easily counterfeited. If this property is set to TRUE, you must also define the passphrase used to decrypt the payload using the following PAYLOAD_PASSPHRASE property as well. The default value of this property is set to FALSE.

public static final String PAYLOAD_PASSPHRASE
This is an optional property that works in conjunction with the PAYLOAD_ENCRYPTED property to set the passphrase used to decrypt secured payloads. If the PAYLOAD_ENCRYPTED property is set to TRUE this property must be set to the same passphrase used during the NFC tag encoding process for the client to properly decode the payload.

public static final long DEBUG_LOG
This is a property that defines if proximity specific debug messages will be printed out to the log cat. The default value of this property is set to FALSE.

Starting the service

To ensure the Smartwhere SDK is started the first time the application is launched after installation, we recommend that you add the following code to the onResume() of your application launch Activity:

@Override
 protected void onResume () {
       super.onResume();
       /* optionally start proximity service */
       ProximityControl.startService(getApplicationContext());
 }

Stopping the service

To stop the service, for example to only have proximity functionality available while the app is in the foreground, call the static stopService method of the ProximityControl object, passing in the application context, as in the following example:

@Override
 protected void onPause () {
       super.onPause();
       /* optionally stop proximity service */
       ProximityControl.stopService(getApplicationContext());
 }

Check for communication errors

If any error in communication occurs between the client and the Smartwhere servers, the communication-error-action intent will be broadcast by the Smartwhere client. The intent will include an extra named “error” which can be recast as a Throwable object type and contain specific information about the error that occurred. This intent is ideal for trapping for temporary loss of connection and displaying the appropriate message to the user.


Yes No Suggest edit
Last updated on February 2, 2016

Proximity Notifications

The Smartwhere Android client SDK will automatically dispatch a proximity notification when a proximity technology event is triggered. By default, this proximity notification will create an Android notification. When the user clicks on the notification the configured action for the event will then be executed.

The Smartwhere client provides a rich framework to customize notification behavior beyond the default behavior. In some cases using the default behavior of automatically creating an Android notification on a proximity technology event may not be the optimal user experience. For example, as a user walks through a location such as retail store or museum it may make sense to filter notifications before displaying them, displaying notifications only while the app is in the foreground or clearing out notifications based on actual location (for example when the user leaves the venue).

You can configure the Smartwhere client to automatically send proximity notifications to a custom IntentService by defining the class in the NOTIFICATION_HANDLER_SERVICE property of the ProximityConfiguration file. For example:

public static final String NOTIFICATION_HANDLER_SERVICE = "com.example.ProximityNotificationService";

The ProximityNotification object will be passed to the onHandleIntent(Intent intent) of the specified IntentService. Extract the ProximityNotification object as follows:

if (intent != null && intent.getAction() != null && intent.getAction().equals("proximity-notification")) {
 
   ProximityNotification proximityNotification = (intent.hasExtra("proximityNotification")) ? (ProximityNotification) intent.getSerializableExtra("proximityNotification") : null;
}

The proximityNotification object will include notification values such as the notification.title and notification.text for the defined locale as well as the event data and proximity object data (Beacon, Wi-Fi, Geofence, NFC or QR object). These objects can be used to provide list views, icon badges or other UI components as well as for creating customized Android notifications.

By using custom action scripts, you can pre-process actions and name/value pairs before they are sent to the client, to further customize the proximity notification experience.

You may pass a proximityNotification object to the Proximity SDK for processing by using the ProximityControl.fireNotification method which will cause the SDK to perform the associated action and add the on-click tracking. Please see the NotificationViewAdapter.java file for a full example of using the fireNotification method from a list view.


Yes No Suggest edit
Last updated on February 2, 2016

Actions

Custom actions

In addition to the built-in actions you can trigger based on proximity events, the Smartwhere platform also supports custom actions. Custom actions are created using server-side scripting and are processed before being sent to the client. Custom actions are ideal for integrating data and logic from external systems into your proximity functionality. For example, you could could use the location of a triggering beacon to find out the weather at that specific location and return that data to the client within an intent extra. For more information on creating custom actions within the administrator, please see Custom Actions.

When a custom action is triggered by a proximity event, the Smartwhere client will generate and broadcast a local intent named custom-proximity-action. This intent will include two extras, object_type and state, that include information about the triggering proximity technology and the triggering state of the technology respectively. The chart below illustrates the possible object types and corresponding states:

04-object_table

In addition to the extras related to the triggering proximity technology, the custom-proximity-action local broadcast intent will also include a serializable extra named action that will contain any information generated by the custom action itself. Any custom variables added to the proximity technology will also be accessible via additional intent extras with the variable name. Please see Variables for more information.

The following example demonstrates the two separate ways to receive custom actions. By default you can register a broadcastreceiver, however that broadcast receiver must be active. In order to receive custom actions regardless of whether any activity is in the foreground, use the CUSTOM_ACTION_ACTIVITY configuration parameter which will launch the specified activity and pass the custom action in the intent. This would be the recommended approach for most custom action deep-linking implementations. Examples of both methods are below:

Receiving custom actions via LocalBroadcastManager

Register Local Broadcast Receiver in the onCreate of the target Activity similar to the following:

LocalBroadcastManager.getInstance(this).registerReceiver(mCustomActionReceiver,
       new IntentFilter("custom-proximity-action"));

Example BroadcastReceiver:

private BroadcastReceiver mCustomActionReceiver = new BroadcastReceiver() {
    @Override
    public void onReceive(Context context, Intent intent) {
        String object_type = (intent.hasExtra("object_type") ? intent.getStringExtra("object_type") : "");
        String state = (intent.hasExtra("state") ? intent.getStringExtra("state") : "0");
        if(intent.hasExtra("action")) {
             Action action = (Action) intent.getSerializableExtra("action");
             int action_type = action.getType();
    /* action_type will be 127 (Custom Action)
    * loop through name/value pairs to get the data
    * i.e. employee_id
    * and order_id
    * */
             List<NameValuePair> nvps = action.getNameValues();
             for(NameValuePair nvp:nvps) {
                 String name = nvp.getName();
                 String value = nvp.getValue();
             }
         }
     }
};

Receiving custom actions via intents passed to an activity

Use the CUSTOM_ACTION_ACTIVITY setting the the ProximityConfiguration to specify which activity should receive the custom actions as shown below:

public static final String CUSTOM_ACTION_ACTIVITY = "com.example.CustomActionActivity";

Test for the custom action intents in the activity onResume method:

@Override
protected void onResume() {
    super.onResume();
    context = getApplicationContext();
    Intent intent = getIntent();
    if (intent != null && intent.getAction() != null && intent.getAction().equals("custom-proximity-action")){
        setIntent(null); // set activity intent to null to clear sticky intent
        String object_type = (intent.hasExtra("object_type") ? intent.getStringExtra("object_type") : "");
        String location_id = (intent.hasExtra("location_id") ? intent.getStringExtra("location_id") : null);
        String state = (intent.hasExtra("state") ? intent.getStringExtra("state") : "0");

        if(intent.hasExtra("action")) {
           Action action = (Action) intent.getSerializableExtra("action");
        ArrayList<NameValuePair> dataList = (ArrayList<NameValuePair>) action.getNameValues();
        }
    }
}

Application store actions

One of the built-in actions offered by the Smartwhere platform is an Application Store action. When a proximity event triggers this action the user will be taken to the corresponding app store for their device’s specific mobile platform to download a configured app.

The Smartwhere client provides a specific local intent named application-launch-action that will automatically be generated and broadcast if the triggering app matches the app configured within the application store action.

The purpose of this intent essentially provides a means to deep link within an app based on a triggering proximity technology event. For example, a user could pass a beacon and if the user had the app previously installed with the associated application store action for the triggering event, the user could then receive a notification, that when clicked, would automatically open the app and deep link them to the correct action.

The application-launch-action intent also includes a serializable extra named action that contains any specific properties related to the Application Store action.

The following example demonstrates creating a BroadcastReceiver receiving custom actions via a LocalBroadcastManager. Register Local Broadcast Receiver in the onCreate of the target Activity similar to the following:

LocalBroadcastManager.getInstance(this).registerReceiver(mApplicationLaunchReceiver,
     new IntentFilter("application-launch-action"));

Example BroadcastReceiver:

private BroadcastReceiver mApplicationLaunchReceiver = new BroadcastReceiver() {
    @Override
    public void onReceive(Context context, Intent intent) {
       // Get extra data included in the Intent
       if(intent.hasExtra("action")) {
          Action action = (Action) intent.getSerializableExtra("action");
          int action_type = action.getType();
/* action_type will be 9 (Application Store)
 you can retrieve the action attributes.
Below we simply start an Activity when an application-launch-action is received
*/
 
          Intent i = new Intent(context,MainActivity.class);
          startActivity(i);
        }
    }
};

Scan Action

The Smartwhere platform supports both NFC and QR based tags as part of its supported proximity technologies. Both NFC and QR tags used with the Smartwhere platform are generated by the Smartwhere administrator and, like the other proximity technologies, can be configured to execute specific actions on a tap or scan proximity event. For more information on creating and configuring tags, please see Tags.

The Smartwhere ProximityControl class includes a built-in method for easily processing these tags: processScan. This method will automatically execute the configured action for the tag when the app context and tag’s unique encoded code is passed to this method.

The following example demonstrates passing the results from the ZXing Barcode Scanner:

public void onActivityResult(int requestCode, int resultCode, Intent intent) {
    if (requestCode == SCAN_ACTIVITY_REQUEST_CODE) {
       if (resultCode == RESULT_OK) {
          String scan_result = intent.getStringExtra("SCAN_RESULT");
/* Include the last segment of url return in scan of QR code i.e. scan_result=http://www.qrcode.com/123456/abc123x */
          String code = Uri.parse(scan_result).getLastPathSegment();
          ProximityControl.processScan(this,code);
        }
    }
}

Yes No Suggest edit
Last updated on February 2, 2016

Attributes and Event Conditions

User Attributes

The Smartwhere SDK provides richer functionality with your app via event conditions and user attributes.

Event Conditions

Using the Smartwhere Administrator, you can configure server-side events with one or more specific conditions that will then be used to score events based upon corresponding user attributes. The conditions may be defined as required and may also have a weighting factor.

The Smartwhere iOS Client SDK provides methods to set a user’s specific values for custom attributes to be compared against the server event conditions. In the case of multiple conditions, the system will intelligently serve the most relevant content to the user based upon whether all the required conditions are met, the offer interval and the combined weighting factor of the conditions met; the Event with the highest weighting that meet all required conditions and adhere to the defined offer interval will be displayed. For more information on setting Event Conditions see Events.

User attributes can be defined through the following methods of the Attribute class:

To clear all of the stored attributes use the clear method.

To add or update an attribute use the setAttributeValue method passing a name and value. If the attribute already exists, the value for the existing attribute will be updated.

To set collection of attributes use the setAttributes method passing a HashMap of name value pairs. This method will overwrite any existing attributes and append any that don’t exist.

To retrieve the value of an attribute use the getAttributeValue method passing a string name of the attribute whose value you wish to return.

To return all attributes use the getAttributes method. This will return a HashMap of name value pairs.

To delete an attribute use the removeAttributeValue method.

Note: User attributes will be stored across user sessions and service restarts.  So situations that require the user attributes be reset, such as a user logout, should use clear method.

 

Tracking Attributes

In addition to user attributes, the Smartwhere client also supports custom tracking attributes. These attributes allow you to add in custom values that you can append to the built in traffic records that are automatically recorded for each user session. These custom tracking values are available for analysis from within the Smartwhere Administrator. One primary use of tracking attributes is to allow integration of your proximity data with your internal systems through a common ID.

Tracking attributes can be defined through the following methods of the TrackingAttribute class.

To clear all of the stored attributes use the clear method.

To add or update a tracking attribute use the setAttributeValue method passing the name and value. If the tracking attribute already exists, the value for the existing tracking attribute will be updated.

To set a collection of tracking attributes use the setAttributes method passing a HashMap of name value pairs. This method will overwrite any existing tracking attributes and append any that don’t exist.

To retrieve the value of a tracking attribute use the getAttributeValue method passing a string name of the tracking attribute whose value you wish to return.

To return all tracking attributes use the getAttributes method. This will return a HashMap of name value pairs.

To delete an attribute use the removeAttributeValue method.

Note: Tracking attributes will be stored across user sessions and service restarts.  So situations that require the user attributes be reset, such as a user logout, should use clear method.

The following example demonstrates adding a simple, single name value pair for an employee ID to be sent with the standard tracking data:

 // Get the trackingAttribute object
 TrackingAttribute trackingAttribute = TrackingAttribute.getInstance(context);
 trackingAttribute.clear();
 
 // Create a map of tracking attributes
 HashMap<String,String> trackingAttributes = new HashMap<>();
 trackingAttributes.put("userId", "987654321");
 trackingAttributes.put("sessionId", "25");
 
 trackingAttribute.setAttributes(userAttributes);
 
 // Add a individual tracking attribute
 trackingAttribute.setAttributeValue("name", "value");
Yes No Suggest edit
Last updated on February 29, 2016

Interstitials

One of the primary event actions supported by the Smartwhere Android client SDK are hosted interstitials. Interstitials are HTML-based content that, when triggered, will do a full screen takeover of your app presenting the content. For more information on Interstitials see Actions.

Closing interstitials from within the HTML

When an interstitial appears, a user can press the device back button to dismiss the interstitial and return to your app. Alternatively the Smartwhere client provides a built-in schema that allows you to implement your own close mechanism from within your HTML content.
To close the interstitial from Javascript enter the following:

window.location = “SmartWhere://close”

To close the interstitial from an HTML anchor element enter the following:

<a href=“SmartWhere://close”>Close me</a>


Yes No Suggest edit
Last updated on February 2, 2016

Project Configuration for Eclipse

Import the Smartwhere library

To add the Smartwhere Framework to your Eclipse Android Project, start by importing the provided proximity_lib library project to your own Android project.

To do this select File > Import… from Eclipse.

05-import

From the Import dialog expand the Android option and select Existing Android Code Into Workspace and click Next to continue.

06-import-project

In the Import Projects dialog enter the complete path to the proximity_lib library project. In the Projects to Import section, check the box next to the proximity_lib. Check the box next to the Copy projects into workspace option. Click the Finish button.

Next, add the proximity_lib to your main application. Right-click your main application from the Package Explorer and select Properties.

08-project-selection

Under the Library section of the Properties dialog click the Add… button.

07-properties

From the Project Selection dialog click the proximity_lib option and then click OK. Click the Apply button the Properties dialog. Click the OK button to close the properties dialog.

Enable manifest merging

Next, open your application’s project.properties file. Enable automatic manifest merging by adding the following line under the #Project Target. comment:

manifestmerger.enabled=true

Include Google Play Location Services

As noted in the Smartwhere SDK requirements, this assumes you already have the Google Play Services (specifically the Locations Services subset) library project included in your main application project. As part of the Google Play Services library installation, your main app should have the following meta-data node in its application manifest:

<meta-data
android:name=”com.google.android.gms.version”
android:value=”@integer/google_play_services_version” />

Please see the Google Play Services documentation for full instructions on including the library within your project.

Yes No Suggest edit
Last updated on February 2, 2016

iOS Client SDK Integration Guide

The following integration guide provides all the information necessary to integrate the Smartwhere iOS Client SDK within your app. Once integrated, your app will have full proximity functionality.

Yes No Suggest edit
Last updated on February 2, 2016

Release Notes

Build 17258 (proximity_sdk-smartwhere-release_17258)

  • Added the ability for events to be removed from the notification tray when exiting from the proximity
  • Changed notification logic to overwrite a notification if the notification is already in the tray
  • Added the ability for delayed events to start the delay when the application is backgrounded
  • Added the ability to replace portions or all of the event notification title and text using client side user or tracking attributes
  • Deprecated the instance user and tracking attribute methods and replaced them with class methods
  • Added class methods to the SmartWhere class to set and get locale
  • Change SDK to weak link CoreLocation and UNUserNotification
  • BUG FIX: fixed miscellaneous minor bugs

Build 17194.2 (SmartWhere_Framework 17194.2)

  • BUG FIX: Change kReachabilityChangedNotification to kSWReachabilityChangedNotification for linker errors when the customer has Reachability installed

Build 17194.1 (SmartWhere_Framework 17194.1)

  • Embed bitcode

Build 17194 (SmartWhere_Framework 17194)

  • Modified to remain dormant until server contact is made
  • Add support UNUserNotifications
  • Add proximityConfiguration.plist for external configuration
  • Implement processMappedEvent and add cancelScanAsNotification
  • Add ttl_minutes to discovery calls and use instead of global if exist
  • Change youtube controller to use https

Build 17087.2 (SmartWhere_Framework 17087.2)

  • Bug Fix: Remove tracking for kicker fences

Build 17087.1 (SmartWhere_Framework 17087.1)

  • Remove dependency for CoreBluetooth

Build 17087 (SmartWhere_Framework 17087)

  • Improve geofence point in polygon algorithm
  • Add configuration for LIMIT_BLE_RANGING and LIMIT_BLE_RANGING_INTERVAL
  • Added exit strategy field to geo fences – EXIT_STRATEGY_POLYGON, EXIT_STRATEGY_RADIUS
  • Various bug fixes

Build 16354 (SmartWhere_Framework 16354)

  • Expose the smartWhere object to tune users
  • Added configuration options
    • PACKAGE_NAME
    • APPLICATION_DATA_UPDATE_TIME
    • APPLICATION_DATA_RETRY_TIME
  • Enable significant location updates
  • Rename reachability library
  • Persist Server config overrides
  • Various bug fixes

Build 16266 (SmartWhere_Framework 16266)

  • Enhanced small geofence algorithm
  • Added configuration options
    • DEBUG_LOGGING
    • ENABLE_LOCATION_PERMISSION_PROMPTING
    • ENABLE_NOTIFICATION_PERMISSION_PROMPTING
    • ENABLE_NOTIFICATION_PERMISSION_PROMPTING
  • Various bug fixes.

Build 16131 (SmartWhere_Framework 16131)

  • BUG FIX: Fixed a crashing issue when an unknown beacon is found.

Build 16124 (SmartWhere_Framework 16124)

  • Added visit ID and duration to tracking
  • Added device conditions – DeviceSecondsSinceInstall, DeviceSecondsSinceUpdate, DeviceSDKVersion

Build 16060 (SmartWhere_Framework 16060)

  • Enhanced the user and tracking attributes apis

Build 16055 (SmartWhere_Framework 16055)

  • Added support for server side client overrides
  • Added support for the silent notification type
  • Added support for BLE scanning filter type to geofences and wifi networks
  • Stopped including framework modules to suppress linker warnings.

Build 16027 (SmartWhere_Framework 16027)

  • Updates to improve network power usage and minor bug fixes

Build 16023 (SmartWhere_Framework 16023)

  • IOS Power consumption optimization
  • Reduced background processing
    • Reduced location updates
    • Reduced BLE range scanning
    • Optimization of Geofence scanning on client SDK startup
    • Update to Geofence Ranging default
    • Update to Geofence Ranging throttle logic; change of default status
  • Added support for client SDK event scheduling
  • Updated SDK to support iOS 9.2

Build 15351 (SmartWhere_Framework 15351)

  • Updates to improve behind the scenes processing and minor bug fixes

Build 15336 (SmartWhere_Framework 15336)

  • Added trigger types to SWNotification class.
  • Added proximity ObjectProperties and EventProperties to SWNotification class
  • Added support for application ID tracking
  • Added support for app start tracking

Build 15308 (SmartWhere_Framework 15308)

  • Added support for advertiser ID tracking
  • Added support for timestamp tracking
  • Addressed an issue with beacon exit log messaging

Build 15278 (SmartWhere_Framework 15278)

  • BUG FIX: Fixed issue where information on the Tracking Queue was not persisted

Build 15238 HF1 (SmartWhere_Framework 15238 hf1)

  • BUG FIX: Added fix to allow implementation of “uri :// close” schema on interstitials
  • Added support for version number on debug log file
  • Improved performance on Actions: URL Redirect, Interstitial and YouTube

Build 15238 (SmartWhere_Framework 15238)

Yes No Suggest edit
Last updated on September 18, 2017

Requirements

This integration guide is built with Xcode version 7.2 and Objective C. The Smartwhere iOS Client SDK support iOS 7 and above. This documentation refers to version RC_16027 of the Smartwhere iOS Client SDK.

Frameworks

The first step in integrating the Smartwhere iOS client into your app is to include the required frameworks within your project. The Smartwhere iOS client requires the following built-in frameworks:

  • Core Location
  • Core Bluetooth
  • System Configuration
  • Ad Support

To add these frameworks to your project select the root project object from the Project Navigator in XCode. Once selected, scroll down to the “Linked Frameworks and Libraries” section of the “General” tab of the project settings. Click the “+” button to bring up the following Frameworks selection dialog:

linked_frameworks

Scroll down and select each framework then click the “Add” button.

Once you’ve included the built-in frameworks above, you must include the Smartwhere framework. To add this framework, simply drag the provided Smartwhere.framework file onto the project root in the Project Navigator as shown in the screen below:

01-frameworks

As soon as you drop in the framework, Xcode will display the above dialog.

NOTE: You must use this drag and drop method to successfully add the Smartwhere framework to your project. In addition you must make sure the “Copy items into destination groups folder (if needed)” option is checked on this dialog. You may leave the other settings in their default state.

Press the Finish button to continue.


Yes No Suggest edit
Last updated on March 30, 2016

Project Configuration

Your app project will require the following configuration settings to function properly with the Smartwhere SDK.

Disable Bitcode

Bitcode is an optional XCode compilation setting that optimizes your app for distribution based on specific device.

The Smartwhere SDK is not currently compatible with Bitcode. As a result,, you’ll need to disable Bitcode support within your app. To disable Bitcode support, go to Project > Build Settings > Build Options and change the “Enable Bitcode” setting to ‘No’:

02-disableBitcode

Add The Objective C Linker Flag

The Smartwhere framework requires that you build your project against the Objective C library. To do this you will need to add -ObjC as a linker flag in the Build Settings > Linking > Add Other Linker Flags, as shown below:

03-addFlag

Location permission description

As a proximity SDK, the Smartwhere client requires location always permissions. In iOS 8 and beyond, you must include an NSLocationAlwaysUsageDescription string entry within your app’s info.plist. The string entered here will appear within the permissions dialog that is presented to the user when the app requests location permissions. This description should provide a clear explanation and value for why the app requires location information.

04-locationPermission

Debug messaging

The Smartwhere client can provide rich debugging messaging regarding current proximity state.

Add SDK Debugging Flag (Optional)

During development, you may wish to see debug logging message from the Smartwhere SDK. To enable logging, go to Target > Info > Custom iOS Target Properties, add com.smartwhere.debugLogging as a Boolean and set to ‘YES’:

05-debug

Suppressing Xcode debug warning messages

In the case that you are developing with a debug build, you can suppress the messages Xcode will generate related to the the Smartwhere SDK since it doesn’t provide debug symbols. To suppress these messages set the Debug Information Format for the project target to DWARF as shown in the screenshot below:

06-suppressDebug


Yes No Suggest edit
Last updated on February 2, 2016

Client Integration

Update your App Delegate

The first step to configure and initialize the Smartwhere Client SDK into your app is to modify your main AppDelegate files.

In your AppDelegate header (.h) file, start by including the Smartwhere Interface (.h) file:

#import <SmartWhere/SmartWhere.h>;

Then, add the following additional Smartwhere property:

@property (readonly) SmartWhere * smartwhere;

Next, within your actual AppDelegate implementation (.m) file, extend the delegate to include support for the SmartwhereDelegate protocol:

@interface AppDelegate () <SmartWhereDelegate>
@end

Implement properties for both the core Smartwhere object and a Smartwhere specific notification object to track the last known event.

@implementation AppDelegate {
 SWNotification * _lastEvent;
}

Configure the Smartwhere Client Object

Before initializing the Smartwhere object you may custom configure a number of client settings. These settings allow you to balance the performance of the client relative to proximity responsiveness and battery consumption.

These settings are configured via an NSDictionary object passed to the initialization alloc method. Please note that if a nil object is passed to the initialization object or an entry is not defined, the default settings will apply.

For testing and development purposes, it is common to use aggressive values to see immediate results. However the default configuration values are the recommended production settings to optimize battery performance.

The following settings are available for configuration:

FENCE_TTL:
This is an optional property that defines how often, in minutes, the client will check to determine if the settings for known cached Geofences should be updated upon entry. By default, this is set to 24 hours. Increasing the frequency of the update time may affect app battery performance.

BEACON_TTL:
This is an optional property that defines how often, in minutes, the client will check to determine if the settings for known cached Beacons should be updated upon entry. By default, this is set to 24 hours. Increasing the frequency of the update time may affect app battery performance.

TAG_TTL:
This is an optional property that defines how often, in minutes, the client will check to determine if the settings for known cached QR Code tags should be updated when scanned. By default, this is set to 24 hours. Increasing the frequency of the update time may affect app battery performance.

TRACK_QUEUE_INTERVAL:
This optional property defines how often, in seconds, the client will flush its queue of collected tracking events and send them to the server. The default is 15 seconds.

GEOFENCE_UPDATE_TIME:
This is an optional property that defines how often, in minutes, the client will ask the server for new geofences based on the client’s current location and update its local cache. By default, this is set to 24 hours. Increasing the update time may affect app battery performance.

DELEGATE_NOTIFICATIONS:
Proximity notifications generated by the Smartwhere SDK can be dispatched as either an iOS Local Notification or sent directly to the Smartwhere delegate. This boolean property defines if proximity notifications will be sent directly to the Smartwhere delegate, regardless if the app is in the foreground or background, bypassing the standard iOS Local Notification dispatch model (in which case the Local Notification will automatically be generated if the app is in the background or sent to the app’s didFireLocalNotification event if in the foreground). This property defaults to False.

Please refer to Proximity Notifications for more information.

ENABLE_GEOFENCE_RANGING:
By default, iOS cannot accurately range for proximity within a Geofence with a radius of less than approximately 200 meters. The Smartwhere client provides its own improved ranging functionality which allows for detection of geofences with less than 100 meter radii. This optional boolean property determines if the Smartwhere geofence ranging functionality should be enabled (YES) or disabled (NO). This property defaults to NO.

Initialize the Smartwhere Client Object

Initialize the Smartwhere object with the initWithAppId method passing in the API key, secret and configuration dictionary.

For convenience the configuration dictionary can be stored in an external plist file. To create a plist file click New File from the File menu. In the “Other” template category, select the Property List template and click Next. Name the file.

Once the plist has been created, you can edit it directly from XCode, as in the screenshot below, populating it with the client configuration settings.

07-configSettings

Once the file has been created, you can use the NSDictionary initWithContentsOfFile method to extract the contents from the plist into a dictionary.

The initWithAppId method should be called from within the app’s didFinishLaunchingWithOptions event. Once the client object has been initialize set it’s delegate property to which over object you’d like to delegate the Smartwhere object, in the example below it is the parent app.

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
 
       NSString* plistPath = [[NSBundle mainBundle] pathForResource:@"SmartwhereConfig" ofType:@"plist"];
       NSDictionary *dict = [[NSDictionary alloc] initWithContentsOfFile:plistPath];
      
       _smartwhere = [[SmartWhere alloc]
                  initWithAppId:@"xxxx"
                  apiKey:@"xxxx"
                  apiSecret:@"xxxx"
                  withConfig: dict];
      _smartwhere.delegate = self;
}

Your unique App ID, API Key and API Secret values can be found within the Admin > Account Information section of the Smartwhere Administrator.

NOTE: The user will not be prompted for location permissions until the Smartwhere object is initialized. Also, be sure to de-initialize the Smartwhere object using the invalidate method when you are done with the Smartwhere object and wish to disable proximity functionality within your app.

Extend Background Processing

Much of the rich proximity functionality offered by the Smartwhere iOS Client SDK is dependent upon the app functioning in the background, for example to detect dwell or hover states and provide high precision ranging.

The Smartwhere client includes two methods to help extend the amount of background processing time afforded to your app: applicationDidEnterBackground and applicationDidBecomeActive. By adding these two methods to the corresponding application lifecycle events will insure that your app has enough background processing cycles to provide the necessary enhanced proximity functionality. Simply add the code below into your AppDelegate.m file.

- (void)applicationDidEnterBackground:(UIApplication *)application {
 [_smartwhere applicationDidEnterBackground];
 }
- (void)applicationDidBecomeActive:(UIApplication *)application {
 [_smartwhere applicationDidBecomeActive];
 }

Check for communication errors

The Smartwhere delegate protocol includes a callback event for communication errors named didReceiveCommunicationError. This method will return an NSError object with details on the specific error in the case that there are communications errors between the client and Smartwhere servers.

The following example demonstrates logging errors with NSLog.

- (void)smartWhere:(SmartWhere*)smartwhere didReceiveCommunicationError:(NSError *)error{
    
   NSString * message;
   
   NSDictionary* userInfo = error.userInfo;
 
   NSError* orgError = userInfo[@"Error"];
 
   switch(error.code){
 
      case 401:
 
         message = [NSString stringWithFormat:@"Make sure your api key and secret are correct."];
 
         break;
 
      case 204:
 
         message = [NSString stringWithFormat:@"Tag not found. There is no properties for code: %@", userInfo[@"code"]];
 
         break;
 
      default:{
 
         NSString * message = [NSString stringWithFormat:@"didReceiveCommunicationError: %@ %ld", error.domain, (long)error.code];
 
         }
 
         NSLog(@"%@", message);
 
      }
 }

Yes No Suggest edit
Last updated on February 4, 2016

Actions

Custom actions

In addition to the built-in actions you can trigger based on proximity events, the Smartwhere platform also supports custom actions. Custom actions are created using server-side scripting and are processed before being sent to the client. Custom actions are ideal for integrating data and logic from external systems into your proximity functionality. For example, you could use the location of a triggering beacon to find out the weather at that specific location and return that data to the client within a name value pair. For more information on creating custom actions within the administrator, please see Custom Actions.

The Smartwhere delegate protocol includes three event callbacks that allow you to trap for incoming custom actions, each specific to a triggering proximity technology: didReceiveCustomBeaconAction, didReceiveCustomFenceAction, and didReceiveCustomTagAction.

Each event callback will include a dictionary of information related to the triggering proximity technology and any values from the server processed custom action itself.

The following example demonstrates each of the possible custom action callbacks. Within each callback, information is extracted from the triggering event and displayed in both the logger and within a UIAlert dialog:

-(void)smartWhere:(SmartWhere *)smartwhere didReceiveCustomBeaconAction:(SWAction *)action withBeaconProperties:(NSDictionary *)beaconProperties triggeredBy:(SWTriggerType)trigger {
    
   NSString * message = [NSString stringWithFormat:@"didReceiveCustomBeaconAction: %ld %@ withBeaconProperties: %@ triggeredBy: %ld",(long) action.actionType, action.values, beaconProperties, (long)trigger];

   NSLog(@"%@", message);
   
   UIAlertView * alert = [[UIAlertView alloc] initWithTitle:@"didReceiveCustomBeaconAction" message:message delegate:self cancelButtonTitle:@"Cancel" otherButtonTitles:nil];

   [alert show];

}


-(void)smartWhere:(SmartWhere *)smartwhere didReceiveCustomFenceAction:(SWAction *)action withFenceProperties:(NSDictionary *)fenceProperties triggeredBy:(SWTriggerType)trigger {

   NSString * message = [NSString stringWithFormat:@"didReceiveCustomFenceAction: %ld %@ withFenceProperties: %@ triggeredBy: %ld",(long) action.actionType, action.values, fenceProperties, (long)trigger];
   
   NSLog(@"%@", message);
    
   UIAlertView * alert = [[UIAlertView alloc] initWithTitle:@"didReceiveCustomFenceAction" message:message delegate:self cancelButtonTitle:@"Cancel" otherButtonTitles:nil];
   
   [alert show];

}


-(void)smartWhere:(SmartWhere *)smartwhere didReceiveCustomTagAction:(SWAction *)action withTagProperties:(NSDictionary *)tagProperties triggeredBy:(SWTriggerType)trigger {
    
   NSString * message = [NSString stringWithFormat:@"didReceiveCustomTagAction: %ld %@ withTagProperties: %@ triggeredBy: %ld",(long) action.actionType, action.values, tagProperties, (long)trigger];
    
   NSLog(@"%@", message);
    
   UIAlertView * alert = [[UIAlertView alloc] initWithTitle:@"didReceiveCustomTagAction" message:message delegate:self cancelButtonTitle:@"Cancel" otherButtonTitles:nil];
    
   [alert show];
    
}

Scan actions

The Smartwhere platform supports QR tags as one of its supported proximity technologies. QR tags used with the Smartwhere platform are generated by the Smartwhere administrator and, like the other proximity technologies, can be configured to execute specific actions on a scan proximity event. For more information on creating and configuring tags, please see Tags.

The Smartwhere iOS client SDK includes a built-in method for easily processing these tags: processScan. This method will automatically execute the configured action for the tag when the tag’s unique code is passed to this method.

The following example demonstrates calling passing a tag code (alphanumberic id) to the processScan method

AppDelegate * delegate = [UIApplication sharedApplication].delegate;
   if (delegate.smartWhere){
   NSString* scanCode = @”zy12fyb”;
   if (scanCode && scanCode.length>0){
      [delegate.smartWhere processScan:scanCode];
   }
}

Yes No Suggest edit
Last updated on February 4, 2016

Proximity Notifications

When a proximity event is triggered, the Smartwhere iOS Client SDK will automatically create a notification. The Smartwhere iOS Client SDK supports two methods for dispatching these proximity notifications. You can configure which method the Smartwhere client uses via the DELEGATE_NOTIFICATIONS property.

Local notification dispatch

The first and default method is to dispatch the proximity notifications as a standard iOS local notification. To use this method the DELEGATE_NOTIFICATIONS property should be set to its default state of NO and the Smartwhere object’s didReceiveLocalNotification method should be called from within the app’s didReceiveLocalNotification method, as in the following example:

 - (void)application:(UIApplication *)application didReceiveLocalNotification:(UILocalNotification *)notification {
 [_smartwhere didReceiveLocalNotification:notification];
 }

If the app is in the background a local notification will automatically be generated and appear in the mobile device’s notification tray. When the user clicks the local notification, your app will open and the configured action, such as an interstitial, will then execute.

If the app is in the foreground when the proximity notification is generated the Smartwhere didReceiveLocalNotification method will then execute the Smartwhere delegate protocol didReceiveLocalNotification method, converting the UILocalNotification into a SWNotification object.

From this point, you can then have your app respond to the proximity notification in whichever way makes the most sense given the app’s context in the foreground. For example, it might make sense to further filter the notification based on the user’s attributes or present location. To ultimately launch the original intended action call the Smartwhere object’s fireLocalNotificationAction method.

The example below displays an alert to the user populated with information from the notification. If the user presses the OK button the notification’s action is executed.

- (void)smartWhere:(SmartWhere *)smartwhere didReceiveLocalNotification:(SWNotification *)notification {
    NSLog(@"SWNotification came in while in the foreground, alerting the user");
    _lastEvent = notification;

   UIAlertView * alert = [[UIAlertView alloc] initWithTitle:notification.title message:notification.message delegate:self cancelButtonTitle:@"Cancel" otherButtonTitles:nil];
   [alert addButtonWithTitle:@"Ok"];
   [alert show];
}

Using the fireLocalNotificationAction method you can then manually trigger the original action associated with the proximity notification (for example to display an interstitial).

- (void)alertView:(UIAlertView *)alertView didDismissWithButtonIndex:(NSInteger)buttonIndex {
   if ([alertView cancelButtonIndex] != buttonIndex && _lastEvent) {
       [_smartwhere fireLocalNotificationAction:_lastEvent];
   }
   _lastEvent = nil;
}

Delegate dispatch

Alternatively, you can configure the Smartwhere iOS SDK client to dispatch any proximity notifications directly to the Smartwhere delegate protocol didReceiveLocalNotification method. This will bypass the creation of an iOS local notification and occur regardless of whether the app is in the foreground or background. To use this method set the DELEGATE_NOTIFICATIONS property to YES.

In this scenario, when a proximity notification is generated it will be dispatched directly to the Smartwhere delegate protocol’s didReceiveLocalNotification method. At this point you have full control over how your app should respond to the proximity notification. For example, you could first check if the app is in the background, increment a notification counter on your app icon and then manually create a Local Notification or flag the user server-side for a future engagement. If the app is in the foreground you could then execute some customer segmentation based on the current app user to determine if the notification should be displayed to the user.

The following example demonstrates the ability to access properties of the notification object.

- (void)smartWhere:(SmartWhere *)smartwhere didReceiveLocalNotification:(SWNotification *)notification {
   _lastEvent = notification;
   /* If DELEGATE_NOTIFICATIONS is set so we will receive all notifications here, otherwise just the foreground notifications */
   /* you can look at properties of the notification */
   NSString *title = notification.title;
   NSString *message = notification.message;
   // get action property "employee_id" if one was added
   NSString *employeeId = notification.action.values[@"employee_id"];
   // get event properties
   NSString *offerInterval=notification.eventProperties[@"offer_interval"];
   //get proximity properties - here we would get the venue_id if it were added to the proximity object
   NSString *venueId=notification.proximityObjectProperties[@"venue_id"];
   // we can look at the source of the event
   switch (notification.triggerType) {
   case swBleDwell:
   // do stuff here
   break;
   case swGeoFenceEnter:
   // do stuff here
   default:
   break;
   }
   /* Optionally store objects in ListView. Simply instruct the SDK to fire the notification action using */
   [_smartWhere fireLocalNotificationAction:_lastEvent];

}

Yes No Suggest edit
Last updated on February 4, 2016

Attributes and Event Conditions

User Attributes

The Smartwhere SDK provides richer functionality with your app via event conditions and user attributes.

Event Conditions

Using the Smartwhere Administrator, you can configure server-side events with one or more specific custom conditions that will be required for the event to be valid. The Smartwhere iOS Client SDK provides methods to set a user’s specific values for custom attributes to be compared against the server event conditions. In the case of multiple conditions, the system will intelligently serve the most relevant content to the user based on how many conditions they meet; the Event with the highest match rate will be displayed. For more information on setting Event Conditions see Events.

User attributes can be defined through the following methods.

Setting user attributes programmatically

The Smartwhere client provides methods for setting, updating, retrieving and removing individual user attributes.  The Smartwhere also client provides methods for setting, updating, retrieving and removing groups of user attributes.
To set an integer based user attribute use the setUserInteger method as in the following example passing in the value and key name:

[_smartwhere setUserInteger:22 forKey:@"age"];

To set a string based user attribute use the setUserString method as in the following example passing in the value and key name:

[_smartwhere setUserString:@"M" forKey:@"gender"];

To retrieve a value for an attribute use the getUserValueForKey method as in the following example:

id value = [_smartwhere getUserValueForKey:@"age"];

To remove the value for an existing key use the removeUserValueForKey method as in the following example:

[_smartwhere removeUserValueForKey:@"age"];

To remove all of the attribute values use the clearUserAttributes method as in the following example:

[_smartwhere clearUserAttributes];

To retrieve the entire list of attributes use the getUserAttributes method as in the following example:

NSDictionary* attributes = [_smartwhere getUserAttributes];

To set the list of attributes use the setUserAttributes method.  This method will update any existing values and append any that don’t exist. example:

 NSMutableDictionary* attributes = [NSMutableDictionary new];
 attributes[@"key"] = @"value";
 attributes[@"key2"] = [NSNumber numberWithInt:2];
 attributes[@"key3"] = @"value3";
[_smartwheresetUserAttributes: attributes];

Setting user attributes using settings bundles

You may also set user attributes via settings bundles. The advantage of this method is that the system will automatically create a user interface for these attributes for the user to control via the app’s specific entry in the device’s settings.

To create a user attribute via a settings bundle simply create a preference item with an identifier with the format: com.smartwhere.settings.ATTRIBUTE_KEY where ATTRIBUTE_KEY is replaced with the attribute key that matches the event condition name.

In the following example, we will create a Settings bundle that contains a single setting titled “Enable Notifications”, with the identifier of “com.smartwhere.settings.notifications.” If events are configured on the server to require that “notifications” be true, then events will only fire if the user setting is enabled.

In the Settings bundle for the app we’d add a preference item of a type Toggle Switch with the Identifier value of com.smartwhere.settings.notifications:

08-toggleSwitch

On the device, the setting for the user attribute will appear as the following:

09-userAttribute

NOTE: iOS 7 will not initialize the values in Settings bundle. You will need to need to manually check to see if the values are nil first and then initialize them accordingly:

if([_smartwhere getUserValueForKey:@"notifications"] == nil) {
 [_smartwhere setUserInteger:1 forKey: @"notifications"];
 }

Built-in client attributes

In addition to supporting custom user attributes, the Smartwhere client also provides 3 built-in client attributes that can be used by event conditions. They are as follows:

DeviceBatteryLevel
This attribute represents the device’s current battery level as a value between 0 to 100.

DeviceChargingState
This attribute represents whether the device is currently being charged. A value of 0 represents no charging state and a value of 1 indicates that the device is currently charging.

DeviceConnectedToNetwork
This attribute represents the device’s current network state. A value of 0 represents that the device currently has no network connection. A value of 1 indicates that the device is currently connected to a wide area network, such as a cell connection. A value of 2 indicates that the device is currently connected to a WiFi network.

Tracking Attributes

In addition to user attributes, the Smartwhere client also supports custom tracking attributes. These attributes allow you to add in custom values that you can append to the built in traffic records that are automatically recorded for each user session. These custom tracking values are available for analysis from within the Smartwhere Administrator. One primary use of tracking attributes is to allow integration of your proximity data with your internal systems through a common ID.

To set a user tracking string use the setUserTrackingString method passing in the value for the tracking attribute and the key name such as the following example:

 [_smartwhere setUserTrackingString:@"123456" forKey:@"device_msisdn"];

To retrieve a user tracking string use the getUserTrackingValueForKey method passing in the key name such as the following example:

 NSString* value = [_smartwheregetUserTrackingValueForKey:@"device_msisdn"];

To remove a user tracking string use the removeUserTrackingValueForKey method passing the key name such as the following example:

[_smartwhere removeUserTrackingValueForKey@"device_msisdn"];

To set a group of user tracking strings use the setUserTrackingAttributes method passing in a dictionary with the tracking attributes and the keys name such as the following example:

 NSMutableDictionary* attributes = [NSMutableDictionary new];
 attributes[@"key"] = @"value";
 attributes[@"key2"] = [NSNumber numberWithInt:2];
 attributes[@"key3"] = @"value3";
[_smartwhere setUserTrackingAttributes:attributes];

To retrieve a dictionary of all of user tracking strings use the getUserTrackingAttributes method such as the following example:

 NSDictionary* attributes = [_smartwhere getUserTrackingAttributes];

To remove all of the user tracking strings use the clearUserTrackingAttributes method such as the following example:

 [_smartwhere clearUserTrackingAttributes];

Yes No Suggest edit
Last updated on March 1, 2016

Interstitials

One of the primary event actions supported by the Smartwhere iOS client SDK are hosted interstitials. Interstitials are HTML-based content that, when triggered, will do a full screen takeover of your app presenting the content. Interstitials provides a built-in, localizable close button that allows the user, when clicked, to dismiss the content and return to your app.

NOTE: By default iOS 9 only allows access to SSL web resources. As a result, interstitial or URI actions that are not sent via SSL will not function properly. In the case that your resources cannot be sent via SSL, Xcode provides a means to override its default behavior via the App Transport Security Settings dictionary option within your app’s info.plist. To modify this setting, first add this entry to your info.plist if it doesn’t already exist. To allow any resources, both SSL and non-SSL set the Allow Arbitrary Loads boolean suboption to YES. To only allow certain domains, select the Domain Exceptions suboption, passing in a dictionary of domains in which SSL should not be enforced.

11-localizeClose

Localizing the close button

By default, the Smartwhere client uses the system style UIBarButtonSystemItemDone which allows the close button title to be localized to the user’s current language selection. To localize the button, the app must first be configured to support localization. This can be done from the Info > Localizations settings for the project.

The localized string is then placed in a file named proximity.strings which contains the following:

“ProximityDoneTitle”=“localized close button title goes here”;

To override the default text of the close button title across all languages, place a copy of this file in the root of the project. To override specific languages, place a copy of this file within the corresponding .lproj folder in the apps bundle, for example fr.lproj/proximity.strings.

12-langOverride

Closing interstitials from within the HTML

You can provide your own close mechanism from within your HTML content by referencing the following built-in Smartwhere close schema.

To close the interstitial from Javascript enter the following:

window.location = “SmartWhere://close”

To close the interstitial from an HTML anchor element enter the following:

<a href="SmartWhere://close">Close me</a>

Yes No Suggest edit
Last updated on February 2, 2016
Suggest Edit