relateddigital-flutter
this library is the official flutter sdk of related digital.
requirements
- ios 10.0 or later
- android api level 21 or later
installation
- edit your project’s
pubspec.yaml
file:
dependencies:
relateddigital_flutter: ^0.2.1
- run
flutter pub get
- import the package:
import 'package:relateddigital_flutter/relateddigital_flutter.dart';
platform-integration
android
- add the following lines to the
repositories
section inproject/build.gradle
maven {url 'http://developer.huawei.com/repo/'} // skip if your app does not support hms
- add the following lines to the
dependencies
section inproject/build.gradle
classpath 'com.google.gms:google-services:4.3.5'
classpath 'com.huawei.agconnect:agcp:1.4.1.300' // skip if your app does not support hms
- add the following lines to the end of
app/build.gradle
apply plugin: 'com.google.gms.google-services'
apply plugin: 'com.huawei.agconnect' // skip if your app does not support hms
- change your minsdkversion to 21.
- add the following services to your
androidmanifest.xml
, within the<application></application>
tags.
<service
android:name="euromsg.com.euromobileandroid.service.eurofirebasemessagingservice"
android:exported="false">
<intent-filter>
<action android:name="com.google.firebase.messaging_event" />
</intent-filter>
</service>
<!-- skip if your app does not support hms -->
<service
android:name="euromsg.com.euromobileandroid.service.eurohuaweimessagingservice"
android:exported="false">
<intent-filter>
<action android:name="com.huawei.push.action.messaging_event" />
</intent-filter>
</service>
- add below meta-data parameters in your androidmanifest.xml
<meta-data android:name="visilabsorganizationid" android:value="visilabsorganizationid" />
<meta-data android:name="visilabssiteid" android:value="visilabssiteid" />
<meta-data android:name="visilabssegmenturl" android:value="http://lgr.visilabs.net" />
<meta-data android:name="visilabsdatasource" android:value="visilabsdatasource" />
<meta-data android:name="visilabsrealtimeurl" android:value="http://rt.visilabs.net" />
<meta-data android:name="visilabschannel" android:value="android" />
<meta-data android:name="visilabsgeofenceurl" android:value="http://s.visilabs.net/geojson" />
<meta-data android:name="visilabsgeofenceenabled" android:value="true" />
<!-- parameters below are optional -->
<meta-data android:name="visilabsrequesttimeoutinseconds" android:value="30" />
<meta-data android:name="visilabsresturl" android:value="visilabsresturl" />
<meta-data android:name="visilabsencrypteddatasource" android:value="visilabsencrypteddatasource" />
<meta-data android:name="visilabstargeturl" android:value="http://s.visilabs.net/json" />
<meta-data android:name="visilabsactionurl" android:value="http://s.visilabs.net/actjson" />
- add
google-services.json
file to your application’sapp
directory. - if your app supports
hms
addagconnect-services.json
file to your application’sapp
directory.
ios
- change the ios platform version to 10.0 or higher in
podfile
platform :ios, '10.0'
- in your project directory, open the file
ios/runner.xcworkspace
with xcode. - enable
push notifications
andbackground modes->remote notifications
capabilities.
- if you want to use advertisingtrackingid with isidfaenabled parameter (see usage below), you need to add this key to your info.plist file for ios 14 and above.
<key>nsusertrackingusagedescription</key>
<string>we use advertising identifier!</string>
usage
initializing
import the library
import 'package:relateddigital_flutter/relateddigital_flutter.dart';
import 'package:relateddigital_flutter/request_models.dart';
import 'package:relateddigital_flutter/response_models.dart';
initialize the library
final relateddigitalflutter relateddigitalplugin = relateddigitalflutter();
@override
void initstate() {
super.initstate();
initlib();
}
future<void> initlib() async {
var initrequest = rdinitrequestmodel(
appalias: platform.isios ? 'ios-alias' : 'android-alias',
huaweiappalias: 'huawei-alias', // pass empty string if your app does not support hms
androidpushintent: 'com.test.mainactivity', // android only
organizationid: 'org_id',
siteid: 'site_id',
datasource: 'data_source',
maxgeofencecount: 20, // ios only
geofenceenabled: true,
inappnotificationsenabled: true,
logenabled: true,
isidfaenabled: true, // ios only
);
await relateddigitalplugin.init(initrequest, _readnotificationcallback);
}
void _readnotificationcallback(dynamic result) {
print(result);
}
push notifications
requesting permission & retrieving token
add the lines below to request push notification permission and retrieve token.
ios
- instead of having to prompt the user for permission to send them push notifications, your app can request provisional authorization. in order to enable provisional authorization, you should set
isprovisional
parameter ofrequestpermission
method totrue
.
string token = '-';
void _gettokencallback(rdtokenresponsemodel result) {
if(result != null && result.devicetoken != null && result.devicetoken.isnotempty) {
setstate(() {
token = result.devicetoken;
});
}
else {
setstate(() {
token = 'token not retrieved';
});
}
}
future<void> requestpermission() async {
await relateddigitalplugin.requestpermission(_gettokencallback, isprovisional: true);
}
rich push notifications
to be able to receive rich notifications with images, buttons and badges, follow the steps below.
ios
- in xcode, add a new notification service extension target and name it notificationservice.
- in your podfile, add below section and then run
pod install
.
target 'notificationservice' do
use_frameworks!
pod 'euromsg'
end
post_install do |installer|
installer.pods_project.targets.each do |target|
flutter_additional_ios_build_settings(target)
target.build_configurations.each do |config|
config.build_settings['application_extension_api_only'] = 'no'
end
end
end
- set notificationservice target’s deployment target to ios 11.
- replace notificationservice.swift file content with the code below.
import usernotifications
import euromsg
class notificationservice: unnotificationserviceextension {
var contenthandler: ((unnotificationcontent) -> void)?
var bestattemptcontent: unmutablenotificationcontent?
override func didreceive(_ request: unnotificationrequest, withcontenthandler contenthandler: @escaping (unnotificationcontent) -> void) {
self.contenthandler = contenthandler
bestattemptcontent = (request.content.mutablecopy() as? unmutablenotificationcontent)
euromsg.didreceive(bestattemptcontent, withcontenthandler: contenthandler)
}
override func serviceextensiontimewillexpire() {
// called just before the extension will be terminated by the system.
// use this as an opportunity to deliver your "best attempt" at modified content, otherwise the original push payload will be used.
if let contenthandler = contenthandler, let bestattemptcontent = bestattemptcontent {
euromsg.didreceive(bestattemptcontent, withcontenthandler: contenthandler)
}
}
}
carousel push notifications
to be able to receive push notifications with carousel, follow the steps below.
ios
- in xcode, add a new notification content extension target and name it notificationcontent.
- in your podfile, add below section and then run
pod install
.
target 'notificationcontent' do
use_frameworks!
pod 'euromsg'
end
- set notificationcontent target’s deployment target to ios 11.
- delete maininterface.storyboard and notificationcontent.swift files. then create a swift file named emnotificationviewcontroller.swift under the notificationcontent folder.
- replace emnotificationviewcontroller.swift file content with the code below.
import uikit
import usernotifications
import usernotificationsui
import euromsg
@available(ios 10.0, *)
@objc(emnotificationviewcontroller)
class emnotificationviewcontroller: uiviewcontroller, unnotificationcontentextension {
let appurl = url(string: "euromsgexample://")
let carouselview = emnotificationcarousel.initview()
var completion: ((_ url: url?, _ userinfo: [anyhashable: any]?) -> void)?
func didreceive(_ notification: unnotification) {
carouselview.didreceive(notification)
}
func didreceive(_ response: unnotificationresponse,
completionhandler completion: @escaping (unnotificationcontentextensionresponseoption) -> void) {
carouselview.didreceive(response, completionhandler: completion)
}
override func loadview() {
completion = { [weak self] url, userinfo in
if let url = url {
self?.extensioncontext?.open(url)
if url.scheme != self?.appurl?.scheme, let userinfo = userinfo {
euromsg.handlepush(pushdictionary: userinfo)
}
}
else if let url = self?.appurl {
self?.extensioncontext?.open(url)
}
}
carouselview.completion = completion
//add if you want to track which element has been selected
carouselview.delegate = self
self.view = carouselview
}
}
/**
add if you want to track which carousel element has been selected
*/
extension emnotificationviewcontroller: carouseldelegate {
func selecteditem(_ element: emmessage.element) {
//add your work...
print("selected element is => (element)")
}
}
- in your notificationcontent/info.plist add below section
<key>nsextension</key>
<dict>
<key>nsextensionattributes</key>
<dict>
<key>unnotificationextensioncategory</key>
<string>carousel</string>
<key>unnotificationextensiondefaultcontenthidden</key>
<false />
<key>unnotificationextensioninitialcontentsizeratio</key>
<real>1</real>
<key>unnotificationextensionuserinteractionenabled</key>
<true />
</dict>
<key>nsextensionpointidentifier</key>
<string>com.apple.usernotifications.content-extension</string>
<key>nsextensionprincipalclass</key>
<string>notificationcontent.emnotificationviewcontroller</string>
</dict>
set push permit
you can only call setnotificationpermission
method to enable or disable push notifications for the application.
relateddigitalplugin.setnotificationpermission(true);
data collection
related digital uses events to collect data from mobile applications. the developer needs to implement the methods provided by sdk. customevent
is a generic method to track user events. customevent
takes 2 parameters: pagename and properties.
- pagename : the current page of your application. if your event is not related to a page view, you should pass a value related to the event. if you pass an empty string the event would be considered invalid and discarded.
- parameters : a collection of key/value pairs related to the event. if your event does not have additional data apart from page name, passing an empty map acceptable.
some of the most common events:
sign up
string userid = 'userid';
// optional
map<string, string> properties = {
'om.b_sgnp':'1'
};
await relateddigitalplugin.signup(userid, properties: properties);
login
string userid = 'userid';
// optional
map<string, string> properties = {
'om.b_login':'1'
};
await relateddigitalplugin.login(userid, properties: properties);
page view
use the following implementation of customevent
method to record the page name the visitor is currently viewing. you may add extra parameters to properties map or you may leave it empty.
string pagename = 'page name';
map<string, string> parameters = {};
await relateddigitalplugin.customevent(pagename, parameters);
product view
use the following implementation of customevent
when the user displays a product in the mobile app.
string pagename = 'product view';
map<string, string> parameters = {
'om.pv' : productcode,
'om.pn' : productname,
'om.ppr' : productprice,
'om.pv.1' : productbrand,
'om.inv': inventory // number of items in stock
};
relateddigitalplugin.customevent(pagename, parameters);
add to cart
use the following implementation of customevent
when the user adds items to the cart or removes.
string pagename = 'cart';
map<string, string> parameters = {
'om.pbid' : basketid,
'om.pb' : 'product1 code;product2 code',
'om.pu' : 'product1 quantity;product2 quantity',
'om.ppr' : 'product1 price*product1 quantity;product2 price*product2 quantity'
};
relateddigitalplugin.customevent(pagename, parameters);
product purchase
use the following implementation of customevent
when the user buys one or more items.
string pagename = 'purchase';
map<string, string> parameters = {
'om.tid' : transactionid,
'om.pp' : 'product1 code;product2 code',
'om.pu' : 'product1 quantity;product2 quantity',
'om.ppr' : 'product1 price*product1 quantity;product2 price*product2 quantity',
'om.exvisitorid' : userid
};
relateddigitalplugin.customevent(pagename, parameters);
product category page view
when the user views a category list page, use the following implementation of customevent
.
string pagename = 'category view';
map<string, string> parameters = {
'om.clist': '12345',
};
relateddigitalplugin.customevent(pagename, parameters);
in app search
if the mobile app has a search functionality available, use the following implementation of customevent
.
string pagename = 'in app search';
map<string, string> parameters = {
'om.oss': searchkeyword,
'om.ossr': searchresult.length,
};
relateddigitalplugin.customevent(pagename, parameters);
banner click
you can monitor banner click data using the following implementation of customevent
.
string pagename = 'banner click';
map<string, string> parameters = {
'om.osb': 'banner name/banner code',
};
relateddigitalplugin.customevent(pagename, parameters);;
add to favorites
when the user adds a product to their favorites, use the following implementation of customevent
.
string pagename = 'add to favorites';
map<string, string> parameters = {
'om.pf' : productcode,
'om.pfu' : '1',
};
relateddigitalplugin.customevent(pagename, parameters);
remove from favorites
when the user removes a product from their favorites, use the following implementation of customevent
.
string pagename = 'add to favorites';
map<string, string> parameters = {
'om.pf' : productcode,
'om.pfu' : '-1',
};
relateddigitalplugin.customevent(pagename, parameters);
logout
to remove all the user related data from local storage, use the method below.
await relateddigitalplugin.logout();
targeting actions
in-app messaging
in-app messages are notifications to your users when they are directly active in your mobile app. to enable in-app messaging feature you need to set the value of inappnotificationsenabled
parameter to true
when calling init
to initialize the sdk.
the existence of a relevant in-app message for an event controlled by after each customevent
call. you can create and customize your in-app messages on https://intelligence.relateddigital.com/#target/targetingaction/talist page of rmc administration panel.
there are 9 types of in-app messages:
pop-up – image, header, text & button | mini-icon&text | full screen-image |
---|---|---|
full screen-image&button | pop-up – image, header, text & button | pop-up-survey |
pop-up – nps with text & button | native alert & actionsheet | nps with numbers |
geofencing
ios
- in xcode, add nslocationalwaysandwheninuseusagedescription and nslocationwheninuseusagedescription keys to the info.plist file.
- in xcode, enable background fetch and location updates background modes.
- when initializing plugin, set geofenceenabled to true. also provide a number for maxgeofencecount parameter (max. 20 supported).
android
- add below permissions in your androidmanifest.xml
<uses-permission android:name="android.permission.access_fine_location"/>
<uses-permission android:name="android.permission.access_coarse_location" />
<uses-permission android:name="android.permission.access_background_location" />
- add below service and receivers in your androidmanifest.xml
<service android:name="com.visilabs.android.gps.geofence.geofencetransitionsintentservice"
android:enabled="true"
android:permission="android.permission.bind_job_service" />
<receiver android:name="com.visilabs.android.gps.geofence.visilabsalarm" android:exported="false"/>
<receiver
android:name="com.visilabs.android.gps.geofence.geofencebroadcastreceiver"
android:enabled="true"
android:exported="true"/>
recommendation
use getrecommendations method as below to retrieve product recommendations. this method takes mandatory zoneid and productcode parameters with optional filters parameter.
import 'package:relateddigital_flutter/recommendation_filter.dart';
future<void> getrecommendations() async {
string zoneid = '6';
string productcode = '';
// optional
map<string, object> filter = {
rdrecommendationfilter.attribute: rdrecommendationfilterattribute.productname,
rdrecommendationfilter.filtertype: rdrecommendationfiltertype.like,
rdrecommendationfilter.value: null
};
list filters = [
filter
];
list result = await widget.relateddigitalplugin.getrecommendations(zoneid, productcode);
// list result = await relateddigitalplugin.getrecommendations(zoneid, productcode, filters: filters);
print(result.tostring());
}
app tracking
(android only)
use sendthelistofappsinstalled method to track installed apps on android.
await widget.relateddigitalplugin.sendthelistofappsinstalled();
add one of the sections below to your androidmanifest.xml in order to use this feature.
option 1
<manifest package="com.example.myapp">
<queries>
<package android:name="com.example.app1" />
<package android:name="com.example.app2" />
</queries>
</manifest>
option 2
<uses-permission android:name="android.permission.query_all_packages"
tools:ignore="queryallpackagespermission" />
Comments are closed.