beaconsmind_sdk

Description:

beaconsmind sdk

Beaconsmind SDK #
Beaconsmind SDK for Flutter.
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 #
Add beaconsmind_sdk to your app pubspec.yaml.
2. Platform setup #
iOS #
Please follow this guide to properly setup iOS platform.
Android #
Please follow this guide to properly setup Android platform.
2. Initialize the SDK #
This will initialize the SDK, and try to retrieve the logged-in user.
await Beaconsmind.instance.initialize(
hostname: 'https://test-develop-suite.azurewebsites.net/',
appVersion: '1.0.0',
androidNotificationBadgeName: 'ic_beacons',
androidNotificationChannelName: 'beaconsmind',
androidNotificationTitle: 'Beaconsmind sdk demo',
androidNotificationText: 'Listening to beacons',
);
copied to clipboard
3. Permissions #
Beaconsmind SDK requires bluetooth and location (whenInUse or always) permissions to detect nearby beacon devices and notification permission to send offers.
In order to request required permissions, consider using the permission_handler package. Make sure to follow the setup required for native iOS & Android.

For testing purposes, consider using Beaconsmind.initializeDevelop() in order to initialize and automatically ask the user for all permissions at once that are required for Beaconsmind SDK to work properly. Make sure to follow the platform setup that is required for it to work:
Android #


Change the MainActivity.kt file to extend FlutterFragmentActivity
instead of FlutterActivity.
import io.flutter.embedding.android.FlutterActivity
import io.flutter.embedding.android.FlutterFragmentActivity

class MainActivity: FlutterFragmentActivity() {
}
copied to clipboard


Use descendant of Theme.AppCompat for your activity theme (both light
and dark). These changes are needed because the Beaconsmind SDK requires
the use of the AppCompat theme for the permission dialog.
<?xml version="1.0" encoding="utf-8"?>
<resources>
<!-- Theme applied to the Android Window while the process is starting when the OS's Dark Mode setting is off -->
<style name="LaunchTheme" parent="Theme.AppCompat.Light.NoActionBar">
<!-- Show a splash screen on the activity. Automatically removed when
Flutter draws its first frame -->
<item name="android:windowBackground">@drawable/launch_background</item>
</style>
<!-- Theme applied to the Android Window as soon as the process has started.
This theme determines the color of the Android Window while your
Flutter UI initializes, as well as behind your Flutter UI while its
running.
This Theme is only used starting with V2 of Flutter's Android embedding. -->
<style name="NormalTheme" parent="Theme.MaterialComponents">
<item name="android:windowBackground">?android:colorBackground</item>
</style>
</resources>
copied to clipboard


iOS #
Make sure to add the following key to your Info.plist file, located in
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>$(PRODUCT_NAME) needs access to your location to detect beacons.</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>$(PRODUCT_NAME) needs access to your location to detect beacons.</string>
<key>NSLocationAlwaysUsageDescription</key>
<string>$(PRODUCT_NAME) needs access to your location to detect beacons.</string>
copied to clipboard
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.
try {
final user = await Beaconsmind.instance.login(
username: _usernameController.text,
password: _passController.text,
);
} catch (e) {
final snackBar = SnackBar(
content: Text(e.toString()),
);
ScaffoldMessenger.of(context).showSnackBar(snackBar);
}
copied to clipboard
To register a new user.
try {
final user = await Beaconsmind.instance.signup(
username: _emailController.text,
firstName: _firstNameController.text,
lastName: _lastNameController.text,
password: _passController.text,
confirmPassword: _passConfirmController.text,
);
Navigator.of(context).pop();
} catch (e) {
final snackBar = SnackBar(
content: Text(e.toString()),
);
ScaffoldMessenger.of(context).showSnackBar(snackBar);
}
copied to clipboard
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.instance.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.
5. Listening to SDK context changes #
The SDK provides a Stream for the user login/logout changes. Beaconsmind.instance.contextEvents()
Beaconsmind.instance.contextEvents().listen((BeaconsmindSdkContext? event) {
// When event is null, the user is not logged in.
// When the event is no nill, the user is logged in.
});
copied to clipboard
6. Notifications #
The SDK uses APNS for iOS, and Firebase for Android. You will need to use two packages from pub.
firebase_messaging
& flutter_apns.
Setting device token #
Check with Beaconsmind support team which push notification provider is used for Android and iOS.
If FCM is used for both Android and iOS, register the device token using the code snippet below.
String? fcmToken = await FirebaseMessaging.instance.getToken();
await Beaconsmind.registerDeviceToken(
token: fcmToken,
platformType: PlatformType.fcm
);
copied to clipboard
If FCM is used for Android and APNS is used for iOS, register device token using the code snippet below.
if (Platform.isAndroid) {
final fcmToken = await FirebaseMessaging.instance.getToken();
if (fcmToken != null) {
await Beaconsmind.instance.registerDeviceToken(
deviceToken: fcmToken,
platformType: PlatformType.fcm,
);
}
}

if (Platform.isIOS) {
final apnsToken = await getApnsToken()
if (apnsToken != null) {
await Beaconsmind.instance.registerDeviceToken(
deviceToken: apnsToken,
platformType: PlatformType.apns,
);
}
}
copied to clipboard
Supporting multiple push notification providers #
Issue
On Android, if there is more than one package used to receive push notifications, for example: moengage_flutter & firebase_messaging, 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 firebase_messaging 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

Add FirebaseMessagingServiceProxy.kt file to your Android app project.
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.
Register the FirebaseMessgingServiceProxy in the app’s manifest.

7. Offers #
Getting offers #

loadOffer({required int id}). Will return a single offer.
loadOffers(). Will return a list of currently active offers.

Interacting with offers #

markOfferAsReceived({required int offerId}). Call this when an ofer is received via push.
markOfferAsRead({required int offerId}). Call this when the user open the offer.
markOfferAsRedeemed({required int offerId}). Call this when the user redeems the offer.

8. Beacons #
Interacting with beacons #

startListeningBeacons().
stopListeningBeacons().
getBeaconsSummary().

Read more about beacons #

iOS setup.
Android setup.

7. Disposing #
Call Beaconsmind.instance.dispose(); to clean app resources and prevent memory leaks.
Platform specifics #
Android #
If using proguard with Beaconsmind Android SDK versions prior to 1.7.0 add a custom rule to your proguard-rules.pro:

-keep class com.beaconsmind.api.models** { *; }