@beaconsmind/ionic-sdk v0.3.0

@beaconsmind/ionic-sdk

Beaconsmind SDK for Ionic.

Prerequisites

As a Beaconsmind client, a contained environment is provided for Beaconsmind services being hosted and maintained by Beaconsmind.

The hostname of the provided environment is required to properly access Beaconsmind API and to use Beaconsmind SDK

example: https://adidas.bms.beaconsmind.com

Please contact Beaconsmind support for the required information about acquiring a valid environment and hostname.

1. Installing

npm install @beaconsmind/ionic-sdk
npx cap sync

Make sure your iOS Deployment Target is 11.0 or above.

Make sure your Android minSdkVersion is 23 or above.

2. Permissions

Beaconsmind SDK requires bluetooth and location permission (whenInUse or always) to detect nearby beacon devices and notification permission to send offers. Consider using a package of choice to request those permissions. Make sure to follow the setup required for native iOS & Android.

3. Initialize the SDK

This will initialize the SDK and try to retrieve the logged-in user. Call this method as soon as your app starts, so the sdk can track all touchpoints and beacon events correctly.

import { Beaconsmind } from '@beaconsmind/ionic-sdk';

const initializeResponse = await Beaconsmind.initialize({
  hostname: 'https://test-develop-suite.azurewebsites.net/',
  appVersion: '0.0.1',
  platformOptions: {
    android: {
      usePassiveScanning: true,
      notification: {
        androidNotificationBadgeName: 'ic_beacons',
        androidNotificationChannelName: 'beaconsmind',
        androidNotificationTitle: 'Beaconsmind sdk demo',
        androidNotificationText: 'Listening to beacons',
      },
    },
  },
});

console.log(initializeResponse);

See:

• initialize(...)

4. Authentication

When using Beaconsmind authentication

This approach implies that the customer data is kept in Beaconsmind backend. Use UserManager.login method to perform customer authentication.

To login existing user.

const loginResponse = await Beaconsmind.login({
  username: usernameValue,
  password: passwordValue,
});

console.log(loginResponse);

See:

• login(...)

To register a new user.

const signUpResponse = await Beaconsmind.instance.signup({
    username: usernameValue,
    firstName: firstNameValue,
    lastName: lastnameValue,
    password: passwordValue,
    confirmPassword: confirmPasswordValue,
  });

console.log(signUpResponse);

See:

• signUp(...)

When using own authentication mechanism

This approach implies that the customer data is kept in clients backend. The authentication is done by the client app before the Beaconsmind API is used. Whenever customer is authenticated, use Beaconsmind.importAccount method to send basic customer data to Beaconsmind. The customer data is updated only the first time the method is called. The client app can track if the customer was imported before and omit personal data from following importAccount calls.

const importAccountResponse = await Beaconsmind.importAccount({
  id: '3287e422-961a-4d47-8eaa-a58e0bd536a1',
  email: 'account@example.com',
  firstName: 'John',
  lastName: 'Doe',
  language: 'en',
  gender: 'male',
  // UNIX timestamp represented in seconds.
  birthDateSeconds: 831589200, 
});

console.log(importAccountResponse);

See:

• importAccount(...)

Log out

In order to log out the current account and stop listening for beacons, call the Beaconsmind.logout() method.

See:

• logout()

6. Notifications

The SDK uses APNS for iOS, and Firebase for Android. You can use the @capacitor/push-notifications package in order to configure it.

Setting device token

import { Beaconsmind } from '@beaconsmind/ionic-sdk';
import { PushNotifications } from '@capacitor/push-notifications';

PushNotifications.addListener('registration', async token => {
  alert('Registration token: ' + token.value);

  const registerDeviceTokenResponse = await Beaconsmind.registerDeviceToken({
    deviceToken: token.value,
  });

  console.log(registerDeviceTokenResponse);
});

See:

• registerDeviceToken(...)

Supporting multiple push notification providers

Issue

On Android, if there is more than one package used to receive push notifications, for example: capacitor-moengage-core & @capacitor/push-notifications, then only one package will be notified about a push notification.

Explanation

Each package used to receive push notifications has it’s on AndroidManifest.xml file (manifest) where it declares a service that should receive and handle the FCM messages — here is an example from the @capacitor/push-notifications package.

When app is built, the app’s manifest is merged with each manifest from packages that it depends on. As a result, the final manifest will contain multiple services declared to receive FCM messages, but the system will deliver push notification only to one of them, the one that is declared earlier.

If there is a service declaration at the app’s manifest, then it will take a precedence over service declarations from packages’ manifest.

Solution

In order to deliver push notifications to services declared by each package, a proxy service declared at the app’s manifest needs to be introduced. It will be responsible for intercepting push notifications and forwarding them to other services coming from used packages.

Implementation

1. Add FirebaseMessagingServiceProxy.kt file to your Android app project.
2. In the FirebaseMessagingServiceProxy file, update messagingServices list with push notification services that you want to notify. Make sure to add necessary imports at the top of the file in order to access them.
3. Register the FirebaseMessgingServiceProxy in the app’s manifest.

7. Offers

Beacons ranging is used to pick up offers. In respect to offers, when users receive pushes about a new offer, read an offer and consume an offer, API calls need to be sent to recognize user activity.

Getting offers

• loadOffers()
• loadOffer(...)

Interacting with offers

• markOfferAsReceived(...)
• markOfferAsRead(...)
• markOfferAsRedeemed(...)

8. Beacons

Interacting with beacons

Beacons feature uses BLE transmitters which can be picked up by devices. In Beaconsmind, BLE transmitters are used to present offers based on a physical location of a device.

Every beacon is defined by it's UUID and major and minor numbers. A list of beacons is persisted and maintained on Beaconsmind environment for each client.

In order to start monitoring nearby beacon devices, call Beaconsmind.startListeningBeacons(). Make sure that the bluetooth & location permissions have been granted. To stop the monitoring process, call Beaconsmind.stopListeningBeacons(). In order to obtain a list of beacon devices that are within range, call Beaconsmind.getBeaconContactsSummary().

See:

• startListeningBeacons()
• stopListeningBeacons()
• getBeaconContactsSummary()

Read more about beacons

• iOS setup.
• Android setup.

Deployment

Log in into the npm package registry by running

npm login

In the root directory, run:

npx release-it

For the wizard questions, answer in the following way:

• Publish @beaconsmind/ionic-sdk to npm? Yes
• Commit? Yes
• Tag (x.y.z)? Yes
• Push? Yes

API

• setMinLogLevel(...)
• initialize(...)
• initializeDevelop(...)
• login(...)
• signUp(...)
• importAccount(...)
• logout()
• getOAuthContext()
• getProfile()
• updateProfile(...)
• registerDeviceToken(...)
• loadOffers()
• loadOffer(...)
• markOfferAsReceived(...)
• markOfferAsRead(...)
• markOfferAsRedeemed(...)
• startListeningBeacons()
• stopListeningBeacons()
• updateHostname(...)
• getBeaconContactsSummary()
• Interfaces
• Type Aliases
• Enums

setMinLogLevel(...)

setMinLogLevel({ minLogLevel }: { minLogLevel: LogLevel; }) => Promise<Response>

Sets the minimum log level.

Returns: Promise<Response>

initialize(...)

initialize(options: InitializeOptions) => Promise<Response>

Initializes the SDK.

Call this method as soon as your app starts, so the sdk can track all touchpoints and beacon events correctly.

Returns: Promise<Response>

initializeDevelop(...)

initializeDevelop(options: InitializeOptions) => Promise<Response>

For development purposes only. Alternative initialization method.

Kickstart sdk testing and integration by a single method call. Invokes initialize and sets the sdk in development mode.

When initialized with this method the sdk requests permissions on it own by.

• Your app must use activity which implements ActivityResultCaller.

Returns: Promise<Response>

login(...)

login({ username, password }: { username: string; password: string; }) => Promise<Response>

Performs login and immediately starts listening for beacons

Returns: Promise<Response>

signUp(...)

signUp(options: SignUpOptions) => Promise<UserIdResponse>

Creates a new account login and immediately starts listening for beacons.

Returns: Promise<UserIdResponse>

importAccount(...)

importAccount(options: ImportAccountOptions) => Promise<UserIdResponse>

When the customer is using 3rd party authentication and not relying on Beaconsmind to keep the customer's private data, this endpoint is used to import the customer into Beaconsmind and to obtain a token with which the app can send tracking data to us. The token does NOT provide access to any personal customer info. If personal data is present in the request, it will only be updated the first time the endpoint is invoked for that customer. Once the authentication is done by the app, the username is sent to Beaconsmind using /api/accounts/import to receive a JWT for access to Beaconsmind backend. In this case, Beaconsmind will not allow any personal data to be accessed and it’s the apps responsibility to only send personal data the first time /api/accounts/import is used. When using import, editing profile is disabled.

Returns: Promise<UserIdResponse>

logout()

logout() => Promise<Response>

Logs out the current account and stops listening for beacons.

Returns: Promise<Response>

getOAuthContext()

getOAuthContext() => Promise<UserIdResponse>

Returns the currently logged in user id.

Returns: Promise<UserIdResponse>

getProfile()

getProfile() => Promise<ProfileResponse>

Returns the currently logged in user profile data.

Returns: Promise<ProfileResponse>

updateProfile(...)

updateProfile(options: any) => Promise<ProfileResponse>

Updates the currently logged in user profile data.

Returns: Promise<ProfileResponse>

registerDeviceToken(...)

registerDeviceToken({ deviceToken }: { deviceToken: string; }) => Promise<Response>

Register the device token in Beaconsmind servers in order receive offers push notifications.

Returns: Promise<Response>

loadOffers()

loadOffers() => Promise<OffersResponse>

Loads the list of offers for the current user.

Returns: Promise<OffersResponse>

loadOffer(...)

loadOffer({ offerId }: { offerId: number; }) => Promise<Offer>

Loads the offer details for the given offer id.

Returns: Promise<Offer>

markOfferAsReceived(...)

markOfferAsReceived({ offerId }: { offerId: number; }) => Promise<Response>

Marks the offer as received.

Call this when an offer is received via push notification.

Returns: Promise<Response>

markOfferAsRead(...)

markOfferAsRead({ offerId }: { offerId: number; }) => Promise<Response>

Marks the offer as read.

Call this when the user opens the offer.

Returns: Promise<Response>

markOfferAsRedeemed(...)

markOfferAsRedeemed({ offerId }: { offerId: number; }) => Promise<Response>

Marks the offer as redeemed.

Call this when the user redeems the offer.

Returns: Promise<Response>

startListeningBeacons()

startListeningBeacons() => Promise<Response>

Starts listening for beacons devices. It requires the following permissions to work:

• location (whenInUse/always)
• bluetooth

Returns: Promise<Response>

stopListeningBeacons()

stopListeningBeacons() => Promise<Response>

Stops listening for beacons devices.

Returns: Promise<Response>

updateHostname(...)

updateHostname({ hostname }: { hostname: string; }) => Promise<Response>

Updates the hostname that the SDK will use to connect to the Beaconsmind servers.

Returns: Promise<Response>

getBeaconContactsSummary()

getBeaconContactsSummary() => Promise<BeaconContactSummaryResponse>

Get a list of all the beacons that are currently in range.

Returns: Promise<BeaconContactSummaryResponse>

Interfaces

InitializeOptions

InitializePlatformOptions

InitializeAndroidOptions

AndroidNotificationOptions

SignUpOptions

ImportAccountOptions

ProfileResponse

Date

Enables basic storage and retrieval of dates and times.

OffersResponse

Offer

BeaconContactSummaryResponse

BeaconContactSummary

A class that holds information about the beacon device.

It consists of the beacon unique identifier (uuid, minor, major), the beacon's name (name) and the name of the store that it is located in.

Additionally, it contains data related to its signal strength and the number of times it was contacted.

Type Aliases

Response

{ result: boolean }

UserIdResponse

{ userId: string } | null

Enums

LogLevel