Powermat SDK

Integration

Guide
Powermat Technologies
Nadav Reuveni, March 20, 2017
Table of Contents

Before you start 3

Developers Introduction 7
Integration 8
Before you start
Overview
Powermat creates points of engagement between business and customers through a network of
connected wireless charging spots. Offering real-time network management solutions.
With Powermat SDK embedded in your app, you can be part of this network and communicate with
your users and gather data in a more efficient ways.

For more information about Powermat, please visit our website at Powermat.com

The Customer journey:

Powermat connects the physical to the digital.
With users having the need to wirelessly charge their phone throughout the day, Powermat creates
the engagement between your customers and your mobile application.
Integrating Powermat SDK will enable your app to activate Powermat charging spots in your
venues, get micro location data and strong BI abilities.
Powermat Platforms

Power charging spots, embedded in the tables, offers fast wireless charging to all mobile
phones.

Powermat IoT Platform enables to add a rich layer of services over wireless power
transmitters and devices by providing users as well as businesses personalized data driven
services
 Powermat application layer - provides the tool to turn power into communication. The
pure act of placing the phone to charge create value turned into a means to engage
Powermat SDK solution:

Powermat SDK adds additional abilities to your app:

Conditional charging: in order to charge their phone, your customers should download
your app and tap on a dedicated button. This activates the charging spot and charging
starts. The button will appear only in a relevant wireless charging venue.
Micro location services: using iBeacon & BLE technology embedded in the charging
spot, the app can determine the customer location when entering the venue, and within
the venue.
Strong BI abilities: with Powermat SDK, all charging events and location data can be
exported to your database.

What is a conditional charging and how does it work?

When a user open your app, it initiate scanning of Beacons in the venue. Once
Powermat Beacon is detected, a tap to charge floating button will appear on the
screen (UI is optional and can be designed in any shape or form). If you have several
branches, it is possible to open the app directly in the relevant branch.

Once user is tapping on that button, the phone will communicate directly with the nearby
charging spots using BLE technology in order to enable charging.
The user is instructed to place the phone (or a Ring accessory, where phone does not
contain an embedded wireless charging technology) on the charging spot and charging
will start.
How does micro location services work with Powermat SDK?

Powermat charging spots are working with iBeacon technology (and will soon support
EddyStone). The Beacon is embedded in the charging spot therefore powered and can be
upgraded remotely. No technician visits are required.
Once Powermat coded beacon is discovered by the app, it is being verified in Powermat
servers which return the venue information.
By knowing the exact venue location, your app can customize its UI and offers to that
location (Welcome to).
With micro location services, you can communicate with your customer in a more efficient
way, by sending targeted offers (either by push, or during app usage before or after
charging, second purchase mechanism etc.).

BI with Powermat SDK

Powermat SDK sends BI events which are related to location and charging. This is a
powerful tool to determine customer behavior in the venue.
o Location services are triggered by Beacon detection and can monitor customer
traffic to the store and inside the store
o Charging events can monitor phone types, most crowded tables, linger time etc.
Developers Introduction

Getting Started

The Powermat SDK gives the host application the following capabilities:

1. Charging in venues related to app

2. Venue discovery service (know which venue the user is in)
3. Micro location discovery service (know where the user in within venue)

The SDK is lightweight and easy to integrate within any app. Within a few function calls it enables
the host app to gain the full SDK capabilities and suit it to the apps needs.

See below an example of two usage flows

Enable charging flow: Finding location/micro location flow:

Integration

iOS

Installing the SDK

The powermat SDK comes as an iOS framework library. In order to integrate it with the app follow
the process below:

1 Open Xcode

4. Open your apps project / create a new application

5. Drag PowermatSDK.framework file into the desired group of Xcodes Project Navigator. In the
displayed dialog check Copy items if needed, select Create groups and check your project
in Add to targets.

Initializing the SDK

1. Add this to the wanted header class in your project :

#import <PowermatSDK/PowermatSDK.h>

1. Add a description for BLE usage in your info.plist file with the key
NSBluetoothPeripheralUsageDescription
2. Declare Implementation of the Init Delegate <PMTCoreSDKDelegate> in your header
file.

1. In your .m file implement those functions:

/**

Protocol for sdk initalizing

*/

@protocol PMTCoreSDKDelegate

/**

In case of initalize error this delegate will be recieved

@param error an error object that contains the status code of the error

*/

-(void)PMTCoreSDKFailedToInitilized:(nonnull NSError *)error;

/**

This delegate will be recieved after SDK initalizing succeeded

*/

-(void)PMTCoreSDKInitilized;
 @end

3. Call the Init method with the parameters appKey and appId that were issued to you. if you dont have
these values please contact powermat support.

/**

This is the init function of the SDK.

@param delegate The delegation implementation object

@param appKey The app key provided by Powermat

@param appID The app id provided by Powermat

*/

-(void)initWithDelegate:(nonnull id<PMTCoreSDKDelegate>)delegate

appKey:(nonnull NSString *)appKey

andAppID:(nonnull NSString *)appID;

Enabling charge

1. After successful init either prepareForTap or discoverLocation should be called to get your app
ready for userTap and enable charge. Both methods include completion and failed blocks and the
difference is the data you get on the completion block. prepareForTap will only get you ready for
userTap while discoverLocation returns data for venue discovery.

prepareForTap:
[[PMTCoreSDK sharedInstance] prepareForTapWithCompletionBlock:^{

/*You are ready to tap*/

} andFailedBlock:^(NSError * _Nonnull error) {

/*Prepare to tap failed with error check the status code to

determine the error reason.*/

}];

discoverLocation:
[[PMTCoreSDK sharedInstance] discoverLocationWithCompletionBlock:^(PMTVenueData *
_Nonnull venueData) {

/*You are ready to tap,

Use the PMTVenueData object or save it for later usage.*/

 } AndFailedBlock:^(NSError * _Nonnull error) {

/*Discover location failed with error check the status code

To determine the error.*/

}];

2. After successful prepareForTap or discoverLocation you can safely call userTap method

if([[PMTCoreSDK sharedInstance] isReadyToTap]){

[[PMTCoreSDK sharedInstance] userTapWithCompletionBlock:^{

/*User Tap succeeded , phone is charging*/

} andFailedBlock:^(NSError * _Nonnull error) {

/*User Tap failed with error check the status code to

determine the error reason*/

}];

If charging did not begin userTap will enter failed block with status you can use to
show in app. See status codes section on this document for further details.

Finding where we are

In order to fetch location data use discoverLocation method after successful Init.

[[PMTCoreSDK sharedInstance] discoverLocationWithCompletionBlock:^(PMTVenueData * _Nonnull

venueData) {

/*Use the PMTVenueData object or save it for later usage. The object
contains all the relevant data for the venue including micro location
data*/

} AndFailedBlock:^(NSError * _Nonnull error) {

/*Discover location failed with error check the status code

To determine the error.*/

}];

If the method resulted with success block a PMTVenueData object is returned, it can be used to
determine if user is in a venue and which venue it is.

The PMTVenueData fields are listed below:

Field Type Purpose

locationId NSString A powermat cloud unique identifier for the

venue

venueId NSString A location ID set by customer

customerKey NSString A customer prefix set by customer

venueName NSString A customer name for the venue

venueCoordinat CLLocationCoordinate The venue coordinates

e 2D

microLocationsI NSArray Array of NSString value representing areas

ds within venues that user is in close proximity
with

distance CLLocationDistance N/A

Using micro location

Micro location data is transmitted through the PMTVenueData object, received by the same
process described in Finding where we are section. The field microLocationsIds contains an
array of customer defined micro location codes that the user is in close proximity with.

The illustration below shows how the microLocationIds help us understand where we are
inside a venue.
Using SDK with Swift

The SDK was written in pure objective-c in order to use it inside you swift project create a
bridge header and import the objective-c framework inside the bridge header.

See Apples documentation regarding bridge headers at

https://developer.apple.com/library/content/documentation/Swift/Conceptual/BuildingCocoaA
pps/MixandMatch.html

API reference

Method Purpose
initWithDelegate initializes SDK

Parameters: appKey, appID

discoverLocationWithC discover the venue we are in, prepare for
ompletionBlock userTap

Parameters: none
prepareForTapWithCom Prepares for userTap
pletionBlock
Parameters: none
userTapWithCompletio Enables charging on Powermat spots
nBlock
Parameters: none
isReadyToTap Checks if userTap can be called

Parameters: none
getAccountID Gets powermat user account id

Parameters: none
Requirements from Host App

Minimum iOS version: 8.0

Bluetooth should be on in order to use the SDK

Android

Installing the SDK

1. In Android studio Click on File tab/New/New Module/ Import .JAR/.AAR Package =>
path to the .AAR

2. In your Build.gradle under dependencies add the following:

compile 'com.android.support:appcompat-v7:XX'

(xx is the latest version of support:appcompact-v7.)

compile group: 'com.google.code.gson', name: 'gson', version: 'XX'

(xx is the latest version of gson)

compile project(':PowermatSDK')

Initializing the SDK

Before beginning it is important to understand that in the SDK each callback object is encapsulated
by a proper ResultReceiver class object. On each initiation of a ResultReceiver object, one should
pass a Handler object related to a Thread on which the result callback should be fire (main thread
VS worker thread etc.)

1. In order for the Powermat SDK to work we need to add permissions

to app/src/main/AndroidManifest.xml

<uses-permission android:name="android.permission.BLUETOOTH" />

<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

<uses-permission android:name="android.permission.INTERNET" />

These permissions enables the discovery of powermat spots in a venue.

2. In your MainActivity add PMT-SDK and the code below:

 import com.powermat.sdk.PMTSdk;
import com.powermat.sdk.handlers.SdkInitResultReceiver;

String appId = YOUR_APP_ID_PROVIDED_BY_POWERMAT;

String appKey = YOUR_APP_KEY_PROVIDED_BY_POWERMAT;

SdkInitResultReceiver sdkInitResultReceiver =
new SdkInitResultReceiver(new Handler());
sdkInitResultReceiver.setSdkInitCallback(
new SdkInitResultReceiver.SdkInitCallback() {
@Override
public Context getContext() {
return context; // should return the current context ex:
// getActivity() /MainActivity.this
}

@Override
public void onInitSuccess() {
//You can now perform discoverLocation call or prepareForTap call
}

@Override
public void onInitFailed(int errorCode) {
//Retry init, check internet connectivity etc.
}
});

// call SDK init

PMTSdk.init(sdkInitResultReceiver, appKey, appId);
Enabling charge

After successful init either prepareForTap or discoverLocation should be called to get your
app ready for userTap and enable charge. Both methods differ in response data,
prepareForTap will get you ready for userTap while discoverLocation returns data for venue
discovery in addition to preparation for userTap.

Getting ready for userTap with prepareForTap:

import com.powermat.sdk.PMTSdk;
import com.powermat.sdk.handlers.PrepareForTapResultReceiver;

PrepareForTapResultReceiver prepareForTapResultReceiver = new

PrepareForTapResultReceiver(new Handler());

prepareForTapResultReceiver.setPrepareForTapCallback(new
PrepareForTapResultReceiver.PrepareForTapCallback() {
@Override
public void onReadyForTap() {
//userTap can be called
}

@Override
public void onPrepareFailed(int errorCode) {
//check error code for info about the failure
}

@Override
public Context getContext() {
return getActivity();
}
});

PMTSdk.prepareForTap(prepareForTapResultReceiver);

Getting ready for userTap with discoverLocation:

import com.powermat.sdk.PMTSdk;
import com.powermat.sdk.model.IPMTLocation;
import com.powermat.sdk.handlers.DiscoverLocationResultReceiver;

DiscoverLocationResultReceiver discoverLocationResultReceiver =
new DiscoverLocationResultReceiver(new Handler());

discoverLocationResultReceiver.setDiscoverLocationCallback(
new DiscoverLocationResultReceiver.DiscoverLocationCallback() {

@Override
public void onPMTLocationNotFound() {
//user is not in a venue
}

@Override
public void onDiscoveryFailed(int errorCode) {
//check error code to understand why discovery has failed
}

@Override
public void onPMTLocationFound(IPMTLocation location) {
 // user is in a venue, check locations for info
}

@Override
public Context getContext() {
return getActivity();
}
});

PMTSdk.discoverLocation(discoverLocationResultReceiver);

After successful prepareForTap or discoverLocation you can safely call userTap

TapToChargeResultReceiver tapToChargeResultReceiver = new TapToChargeResultReceiver(new
Handler());

tapToChargeResultReceiver.setTapToChargeCallback(new
TapToChargeResultReceiver.TapToChargeCallback() {
@Override
public Context getContext() {
return getActivity();
}

@Override
public void onChargeSucceeded() {
}

@Override
public void onChargeFailed(int errorCode) {
}
});

PMTSdk.userTap(tapToChargeResultReceiver);

If charging did not begin userTap will enter failed block with status you can use to show
in app. See status codes section on this document for further details.
Finding where we are

In order to fetch location data use discoverLocation method after successful Init:

DiscoverLocationResultReceiver discoverLocationResultReceiver =
new DiscoverLocationResultReceiver(new Handler());

discoverLocationResultReceiver.setDiscoverLocationCallback(
new DiscoverLocationResultReceiver.DiscoverLocationCallback() {

@Override
public void onPMTLocationNotFound() {

@Override
public void onDiscoveryFailed(int errorCode) {
//check error code to understand why discovery has failed
}

@Override
public void onPMTLocationFound(IPMTLocation location) {
//query location to get information about the venue
}

@Override
public Context getContext() {
return getActivity();
}
});

PMTSdk.discoverLocation(discoverLocationResultReceiver);

If the method succeeded and venue was found onPMTLocationFound will be called, query the
location parameter to get information regarding the venue the user is in.

The location properties are listed below:

Property Type Purpose

getLocationid String A powermat cloud unique identifier for the

venue

getVenueId String A location ID set by customer

getCustomerId String A customer prefix set by customer

getVenueName String A customer name for the venue

getVenueCoordina LatLng The venue coordinates

tes

microLocationsIds String[] Array of String value representing areas within

venues that user is in close proximity with

getDistance int N/A

Using micro location

Micro location data is transmitted through the IPMTLocation interface, The interface includes an
array property which contains Micro location ids (String), you can retrieve this object by calling
Discover location as described in the section above, the array of micro location ids can be empty if
user is not close to a Charging Spot.

The illustration below shows how the microLocationIds help us understand where we are
inside a venue.
API reference

Method Purpose
init initializes SDK

Parameters: initResultReceiver, appID,

appKey
discoverLocation discover the venue we are in, prepare for
userTap

Parameters:
discoverLocationResultReceiver
prepareForTapWithCo Prepares for userTap
mpletionBlock
Parameters: none
userTapWithCompletio Enables charging on Powermat spots
nBlock
Parameters: none
isReadyToTap Checks if userTap can be called

Parameters: none
getAccountID Gets powermat user account id

Parameters: none

Known issues & limitations

Older Android SDK Version

The minimum required android SDK version for the Powermat SDK to function is 19 (KitKat)
If your app supports lower SDK versions, to avoid build failures, you will need to add the following
lines to your manifest:

<uses-sdk android:targetSdkVersion=TARGET_SDK_VERSION
android:minSdkVersion=MIN_PROJECT_SDK_VERSION
tools:overrideLibrary="com.google.android.gms.tasks,
com.google.android.gms.location,com.google.android.gms.base,com.google.android.gms,com.powermat.s
dk"/>

Switch TARGET_SDK_VERSION with your projects target SDK version

Switch MIN_PROJECT_SDK_VERSION with your projects minimum SDK version
If app runs on device running android version older than KitKat, upon Powermat SDK init
IllegalAndroidSDKVersionException exception will be thrown.
Status Codes

Methods in SDK will return error codes in case that operation went wrong, the list below explains
what are the different error codes you may get

Error Code Description

1 appId/appKey arent valid

2 init failed

3 SDK not initialized

4 bluetooth is off/location permission is not allowed in android

20 No location was found