NPAW Plugin for Flutter
Table of contents
1. Install the library as a dependency
Run the next command on your project's folder:
flutter pub add lib_npaw_plugin_flutter
This will add a line like this to your package's pubspec.yaml (and run an implicit flutter pub get):
dependencies:
lib_npaw_plugin_flutter: ^1.1.0
2. Integrate the library into your code
A very good start to try our library would be to create a brand-new flutter app and try to integrate our package within it. This will help you find error more easily and simplify any issues you might find.
Note: Make sure to use the version
2.6.1
of thevideo_player
First of all, add the next line into your build.gradle
file inside the allprojects
section:
maven {
url "https://npaw.jfrog.io/artifactory/youbora/"
}
Make sure to paste the next line in order to import the library into your files:
import 'package:lib_npaw_plugin_flutter/lib_npaw_plugin_flutter.dart';
Examples on how to integrate can be find in the /example
app located in the root folder of this project. Make sure to pay attention to the main.dart
file to check how to initialize the plugin.
Here's how it's done:
/*** /lib_npaw_plugin_flutter/example/lib/main.dart ***/
class _MyAppState extends State<MyApp> {
// Initialize the library
final plugin = LibNpawPluginFlutter();
@override
void initState() {
super.initState();
plugin.setupNpawPlugin('myAccountCode'); // Setup the plugin with the account code
plugin.setLogLevel(NpawConstants.LogLevel_debug); // Set the debug level
plugin.options.setAppName('Flutter Example App'); // Set the desired options
}
// ...
}
A list of all the available options can be found further in this document.
As you can see scrolling down in the same file, we've created two different tabs, one for AppAnalytics
and the other for VideoAnalytics
.
/*** /lib_npaw_plugin_flutter/example/lib/main.dart ***/
@override
Widget build(BuildContext context) {
return MaterialApp(
home: DefaultTabController(
length: 2,
child: Scaffold(
appBar: AppBar(
title: const Text('NPAW Plugin Example'),
bottom: const TabBar(
tabs: [
Tab(text: 'App Analytics'),
Tab(text: 'Video Analytics'),
],
),
),
body: TabBarView(
children: [
AppAnalyticsScreen(plugin: plugin), // Here we instantiate the logic of the AppAnalytics screen injecting the plugin
VideoAnalyticsScreen(plugin: plugin) // Here we instantiate the logic of the VideoAnalytics screen injecting the plugin
],
),
),
),
);
}
To call the functions of the plugin, just use the module within it (options
, appAnalytics
and videoAnalytics
) as we can see in the next example:
/*** /example/lib/screens/app_analytics.dart ***/
import 'package:flutter/material.dart';
import 'package:lib_npaw_plugin_flutter/lib_npaw_plugin_flutter.dart';
class AppAnalyticsScreen extends StatelessWidget {
final LibNpawPluginFlutter plugin;
const AppAnalyticsScreen({super.key, required this.plugin});
@override
Widget build(BuildContext context) {
return Center(
child: Column(
mainAxisAlignment: MainAxisAlignment.center,
children: <Widget>[
const SizedBox(height: 20.0),
SizedBox(
width: 200.0,
child: ElevatedButton(
onPressed: () {
const screenName = "Start Session - Screen Name";
const Map<String, String> dimensions = {
"DimensionName1": "DimensionValue1",
"DimensionName2": "DimensionValue2"
};
plugin.appAnalytics.startSession(screenName, dimensions); // Call the Start Session method
},
child: const Text('Start Session'),
),
),
const SizedBox(height: 10.0),
SizedBox(
width: 200.0,
child: ElevatedButton(
onPressed: () {
plugin.appAnalytics.endSession(); // Call the End Session method
},
child: const Text('End Session'),
),
),
const SizedBox(height: 10.0),
SizedBox(
width: 200.0,
child: ElevatedButton(
onPressed: () {
const screenName = "Navigation - Screen Name";
plugin.appAnalytics.navigation(screenName); // Call the Navigation method
},
child: const Text('New Navigation'),
),
),
const SizedBox(height: 10.0),
SizedBox(
width: 200.0,
child: ElevatedButton(
onPressed: () {
Map<String, String> dimensions = {
'dimension1': 'dimensionValue1',
'dimension2': 'dimensionValue2',
'dimension3': 'dimensionValue3'
};
Map<String, double> values = {
'value1': 26,
'value2': 1996
};
plugin.appAnalytics.customEvent("App Analytics Event", dimensions, values);
},
child: const Text('New Custom Event'),
),
),
],
),
);
}
}
To integrate the VideoAnalytics
module, some params are needed to be given to the plugin once the VideoPlayerController
has been initialized (1).
On one hand, we have to send to the plugin's option three pieces of information:
- (2): The
contentTitle
using theplugin.options.setContentTitle('Title of my content')
method - (3): The
contentResourse
URL using theplugin.options.setContentResource('http://resource-url.com')
method. - (4): The
playerVersion
of the current player. If needed, check on thepubspeck.lock
to find it. - (5): The
VideoPlayerController
of the player used on the screen using theplugin.videoAnalytics.setAdapter(_controller)
method.
/*** /example/lib/screens/video_analytics.dart ***/
class _VideoAnalyticsScreenState extends State<VideoAnalyticsScreen> {
late VideoPlayerController _controller;
late Future<void> _initializeVideoPlayerFuture;
late ChewieController _chewieController;
final mediaResource = "https://storage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4";
@override
void initState() {
super.initState();
_controller = VideoPlayerController.network(mediaResource);
_initializeVideoPlayerFuture = _controller.initialize().then((_) {
// (1) This code is run when the VideoPlayerController has been initialized
widget.plugin.options.setContentTitle("The title of my content"); // (2) Add the content title
widget.plugin.options.setContentResource(mediaResource); // (3) Add the content resource url
widget.plugin.videoAnalytics.setPlayerVersion("video_player-2.6.1"); // (4) Set the player version
widget.plugin.videoAnalytics.setAdapter(_controller); // (5) Setup the adapter
});
_chewieController = ChewieController(
videoPlayerController: _controller
);
}
@override
void dispose() {
widget.plugin.videoAnalytics.disposeAdapter();
_controller.dispose();
_chewieController.dispose();
super.dispose();
}
// ...
}
Make sure to check the example app located in /lib_npaw_plugin_flutter/example/lib
folder to learn from our own integration.
Plugin Modules
The NPAW plugin is divided in three different modules: Options
, AppAnalytics
and VideoAnalytics
and each single one it's responsible of a single feature.
1. Options
This class provides an interface for configuring various options for the application and the user.
Method Overview
setAccountCode
: Sets the account code for the user.setUsername
: Sets the username for the user.setUserType
: Sets the user type for the user.setUserEmail
: Sets the user email for the user.setDeviceCode
: Sets the device code for the user's device.setDeviceModel
: Sets the device model for the user's device.setDeviceBrand
: Sets the device brand for the user's device.setDeviceType
: Sets the device type for the user's device.setDeviceOsName
: Sets the device OS name for the user's device.setDeviceOsVersion
: Sets the device OS version for the user's device.setDeviceIsAnonymous
: Sets whether the user's device is anonymous or not.setContentResource
: Sets the content resource for the application.setContentIsLive
: Sets whether the content is live or not.setContentTitle
: Sets the content title for the application.setProgram
: Sets the program for the application.setContentDuration
: Sets the content duration for the application.setContentBitrate
: Sets the content bitrate for the application.setContentThroughput
: Sets the content throughput for the application.setContentRendition
: Sets the content rendition for the application.setContentLanguage
: Sets the content language for the application.setAppName
: Sets the application name.setAppReleaseVersion
: Sets the application release version.setCustomDimension1
: Sets custom dimension 1.setCustomDimension2
: Sets custom dimension 2.setCustomDimension3
: Sets custom dimension 3.setCustomDimension4
: Sets custom dimension 4.setCustomDimension5
: Sets custom dimension 5.setCustomDimension6
: Sets custom dimension 6.setCustomDimension7
: Sets custom dimension 7.setCustomDimension8
: Sets custom dimension 8.setCustomDimension9
: Sets custom dimension 9.setCustomDimension10
: Sets custom dimension 10.setCustomDimension11
: Sets custom dimension 11.setCustomDimension12
: Sets custom dimension 12.setCustomDimension13
: Sets custom dimension 13.setCustomDimension14
: Sets custom dimension 14.setCustomDimension15
: Sets custom dimension 15.setCustomDimension16
: Sets custom dimension 16.setCustomDimension17
: Sets custom dimension 17.setCustomDimension18
: Sets custom dimension 18.setCustomDimension19
: Sets custom dimension 19.setCustomDimension20
: Sets custom dimension 20.setContentCdn
: Sets the content CDN.setParseCdnNode
: Sets the parse CDN node for the user.setBackgroundEnabled
: Sets the background enabled status for the user.setContentStreamingProtocol
: Sets the content streaming protocol for the user.setContentPackage
: Sets the content package for the user.setContentSaga
: Sets the content saga for the user.setContentTvShow
: Sets the content TV Show for the user.setContentSeason
: Sets the content season for the user.setContentEpisodeTitle
: Sets the content episode title for the user.setContentChannel
: Sets the content channel for the user.setContentId
: Sets the content ID for the user.setContentGracenoteId
: Sets the content gracenote ID for the user.setContentType
: Sets the content type for the user.setContentGenre
: Sets the content genre for the user.setContentSubtitles
: Sets the content subtitles for the user.setContentPlaybackType
: Sets the content playback type for the user.setContentDrm
: Sets the content DRM for the user.
Methods
setAccountCode
Future<void> setAccountCode(String accountCode)
Sets the account code for the user.
Parameters:
accountCode
: The account code for the user, represented as aString
.
setUsername
Future<void> setUsername(String username)
Sets the username for the user.
Parameters:
username
: The username for the user, represented as aString
.
setUserType
Future<void> setUserType(String userType)
Sets the user type for the user.
Parameters:
userType
: The user type for the user, represented as aString
.
setUserEmail
Future<void> setUserEmail(String userEmail)
Sets the user email for the user.
Parameters:
userEmail
: The user email for the user, represented as aString
.
setDeviceCode
Future<void> setDeviceCode(String deviceCode)
Sets the device code for the user's device.
Parameters:
deviceCode
: The device code for the user's device, represented as aString
.
setDeviceModel
Future<void> setDeviceModel(String deviceModel)
Sets the device model for the user's device.
Parameters:
deviceModel
: The device model for the user's device, represented as aString
.
setDeviceBrand
Future<void> setDeviceBrand(String deviceBrand)
Sets the device brand for the user's device.
Parameters:
deviceBrand
: The device brand for the user's device, represented as aString
.
setDeviceType
Future<void> setDeviceType(String deviceType)
Sets the device type for the user's device.
Parameters:
deviceType
: The device type for the user's device, represented as aString
.
setDeviceOsName
Future<void> setDeviceOsName(String deviceOsName)
Sets the device OS name for the user's device.
Parameters:
deviceOsName
: The device OS name for the user's device, represented as aString
.
setDeviceOsVersion
Future<void> setDeviceOsVersion(String deviceOsVersion)
Sets the device OS version for the user's device.
Parameters:
deviceOsVersion
: The device OS version for the user's device, represented as aString
.
setDeviceIsAnonymous
Future<void> setDeviceIsAnonymous(bool deviceIsAnonymous)
Sets whether the user's device is anonymous or not.
Parameters:
deviceIsAnonymous
: Abool
value representing if the device is anonymous.
setContentResource
Future<void> setContentResource(String contentResource)
Sets the content resource for the application.
Parameters:
contentResource
: The content resource for the application, represented as aString
.
setContentIsLive
Future<void> setContentIsLive(bool contentIsLive)
Sets whether the content is live or not.
Parameters:
contentIsLive
: Abool
value representing if the content is live.
setContentTitle
Future<void> setContentTitle(String contentTitle)
Sets the content title for the application.
Parameters:
contentTitle
: The content title for the application, represented as aString
.
setProgram
Future<void> setProgram(String program)
Sets the program for the application.
Parameters:
program
: The program for the application, represented as aString
.
setContentDuration
Future<void> setContentDuration(Duration contentDuration)
Sets the content duration for the application.
Parameters:
contentDuration
: The content duration for the application, represented as a Flutter's Duration object.
setContentBitrate
Future<void> setContentBitrate(int contentBitrate)
Sets the content bitrate for the application.
Parameters:
contentBitrate
: The content bitrate for the application, represented as anint
.
setContentThroughput
Future<void> setContentThroughput(int contentThroughput)
Sets the content throughput for the application.
Parameters:
contentThroughput
: The content throughput for the application, represented as anint
.
setContentRendition
Future<void> setContentRendition(String contentRendition)
Sets the content rendition for the application.
Parameters:
contentRendition
: The content rendition for the application, represented as aString
.
setContentLanguage
Future<void> setContentLanguage(String contentLanguage)
Sets the content language for the application.
Parameters:
contentLanguage
: The content language for the application, represented as aString
.
setAppName
Future<void> setAppName(String appName)
Sets the application name.
Parameters:
appName
: The application name, represented as aString
.
setAppReleaseVersion
Future<void> setAppReleaseVersion(String appReleaseVersion)
Sets the application release version.
Parameters:
appReleaseVersion
: The application release version, represented as aString
.
setCustomDimension1
Future<void> setCustomDimension1(String customDimension1)
Sets custom dimension 1.
Parameters:
customDimension1
: The custom dimension 1 value, represented as aString
.
setCustomDimension2
Future<void> setCustomDimension2(String customDimension2)
Sets custom dimension 2.
Parameters:
customDimension2
: The custom dimension 2 value, represented as aString
.
setCustomDimension3
Future<void> setCustomDimension3(String customDimension3)
Sets custom dimension 3.
Parameters:
customDimension3
: The custom dimension 3 value, represented as aString
.
setCustomDimension4
Future<void> setCustomDimension4(String customDimension4)
Sets custom dimension 4.
Parameters:
customDimension4
: The custom dimension 4 value, represented as aString
.
setCustomDimension5
Future<void> setCustomDimension5(String customDimension5)
Sets custom dimension 5.
Parameters:
customDimension5
: The custom dimension 5 value, represented as aString
.
setCustomDimension6
Future<void> setCustomDimension6(String customDimension6)
Sets custom dimension 6.
Parameters:
customDimension6
: The custom dimension 6 value, represented as aString
.
setCustomDimension7
Future<void> setCustomDimension7(String customDimension7)
Sets custom dimension 7.
Parameters:
customDimension7
: The custom dimension 7 value, represented as aString
.
setCustomDimension8
Future<void> setCustomDimension8(String customDimension8)
Sets custom dimension 8.
Parameters:
customDimension8
: The custom dimension 8 value, represented as aString
.
setCustomDimension9
Future<void> setCustomDimension9(String customDimension9)
Sets custom dimension 9.
Parameters:
customDimension9
: The custom dimension 9 value, represented as aString
.
setCustomDimension10
Future<void> setCustomDimension10(String customDimension10)
Sets custom dimension 10.
Parameters:
customDimension10
: The custom dimension 10 value, represented as aString
.
setCustomDimension11
Future<void> setCustomDimension11(String customDimension11)
Sets custom dimension 11.
Parameters:
customDimension11
: The custom dimension 11 value, represented as aString
.
setCustomDimension12
Future<void> setCustomDimension12(String customDimension12)
Sets custom dimension 12.
Parameters:
customDimension12
: The custom dimension 12 value, represented as aString
.
setCustomDimension13
Future<void> setCustomDimension13(String customDimension13)
Sets custom dimension 13.
Parameters:
customDimension13
: The custom dimension 13 value, represented as aString
.
setCustomDimension14
Future<void> setCustomDimension14(String customDimension14)
Sets custom dimension 14.
Parameters:
customDimension14
: The custom dimension 14 value, represented as aString
.
setCustomDimension15
Future<void> setCustomDimension15(String customDimension15)
Sets custom dimension 15.
Parameters:
customDimension15
: The custom dimension 15 value, represented as aString
.
setCustomDimension16
Future<void> setCustomDimension16(String customDimension16)
Sets custom dimension 16.
Parameters:
customDimension16
: The custom dimension 16 value, represented as aString
.
setCustomDimension17
Future<void> setCustomDimension17(String customDimension17)
Sets custom dimension 17.
Parameters:
customDimension17
: The custom dimension 17 value, represented as aString
.
setCustomDimension18
Future<void> setCustomDimension18(String customDimension18)
Sets custom dimension 18.
Parameters:
customDimension18
: The custom dimension 18 value, represented as aString
.
setCustomDimension19
Future<void> setCustomDimension19(String customDimension19)
Sets custom dimension 19.
Parameters:
customDimension19
: The custom dimension 19 value, represented as aString
.
setCustomDimension20
Future<void> setCustomDimension20(String customDimension20)
Sets custom dimension 20.
Parameters:
customDimension20
: The custom dimension 20 value, represented as aString
.
setContentCdn
Future<void> setContentCdn(String contentCdn)
Sets the content CDN for the application.
Parameters:
contentCdn
: The content CDN for the application, represented as aString
.
setParseCdnNode
Future<void> setParseCdnNode(bool parseCdnNode)
Sets the parse CDN node for the application.
Parameters:
parseCdnNode
: The parse CDN node for the application, represented as abool
.
setBackgroundEnabled
Future<void> setBackgroundEnabled(bool backgroundEnabled)
Sets the background enabled status for the application.
Parameters:
backgroundEnabled
: The background enabled status for the application, represented as abool
.
setContentStreamingProtocol
Future<void> setContentStreamingProtocol(String contentStreamingProtocol)
Sets the content streaming protocol for the application.
Parameters:
contentStreamingProtocol
: The content streaming protocol for the application, represented as aString
.
setContentPackage
Future<void> setContentPackage(String contentPackage)
Sets the content package for the application.
Parameters:
contentPackage
: The content package for the application, represented as aString
.
setContentSaga
Future<void> setContentSaga(String contentSaga)
Sets the content saga for the application.
Parameters:
contentSaga
: The content saga for the application, represented as aString
.
setContentTvShow
Future<void> setContentTvShow(String contentTvShow)
Sets the content TV Show for the application.
Parameters:
contentTvShow
: The content TV Show for the application, represented as aString
.
setContentSeason
Future<void> setContentSeason(String contentSeason)
Sets the content season for the application.
Parameters:
contentSeason
: The content season for the application, represented as aString
.
setContentEpisodeTitle
Future<void> setContentEpisodeTitle(String contentEpisodeTitle)
Sets the content episode title for the application.
Parameters:
contentEpisodeTitle
: The content episode title for the application, represented as aString
.
setContentChannel
Future<void> setContentChannel(String contentChannel)
Sets the content channel for the application.
Parameters:
contentChannel
: The content channel for the application, represented as aString
.
setContentId
Future<void> setContentId(String contentId)
Sets the content ID for the application.
Parameters:
contentId
: The content ID for the application, represented as aString
.
setContentGracenoteId
Future<void> setContentGracenoteId(String contentGracenoteId)
Sets the content gracenote ID for the application.
Parameters:
contentGracenoteId
: The content gracenote ID for the application, represented as aString
.
setContentType
Future<void> setContentType(String contentType)
Sets the content type for the application.
Parameters:
contentType
: The content type for the application, represented as aString
.
setContentGenre
Future<void> setContentGenre(String contentGenre)
Sets the content genre for the application.
Parameters:
contentGenre
: The content genre for the application, represented as aString
.
setContentSubtitles
Future<void> setContentSubtitles(String contentSubtitles)
Sets the content subtitles for the application.
Parameters:
contentSubtitles
: The content subtitles for the application, represented as aString
.
setContentPlaybackType
Future<void> setContentPlaybackType(String contentPlaybackType)
Sets the content playback type for the application.
Parameters:
contentPlaybackType
: The content playback type for the application, represented as aString
.
setContentDrm
Future<void> setContentDrm(String contentDrm)
Sets the content DRM for the application.
Parameters:
contentDrm
: The content DRM for the application, represented as aString
.
2. AppAnalytics
This class provides an interface for managing application analytics sessions and navigation.
Method Overview
startSession
: Starts a new analytics session.endSession
: Ends the current analytics session.navigation
: Notifies the analytics system of a navigation event.customEvent
: Notifies the analytics system of a custom event.
Methods
startSession
Future<void> startSession(String screenName, Map<String, String>? dimensions)
Starts a new analytics session, with a specified screen name and optional dimensions.
Parameters:
screenName
: The name of the initial screen, represented as aString
.dimensions
(Optional): AMap<String, String>
containing custom dimensions for the session.
endSession
Future<void> endSession()
Ends the current analytics session.
navigation
Future<void> navigation(String screenName)
Notifies the analytics system of a navigation event, with a specified screen name.
Parameters:
screenName
: The name of the screen being navigated to, represented as aString
.
customEvent
Future<void> customEvent(String eventName, Map<String, String>? dimensions, Map<String, Double>? values)
Notifies the analytics system of a custom event.
Parameters:
eventName
: The name of the initial screen, represented as aString
.dimensions
(Optional): AMap<String, String>
containing custom dimensions for the session.values
(Optional): AMap<String, Double>
containing the values for the session.
3. VideoAnalytics
This class provides an interface for managing video analytics events and sessions.
Method Overview
setAdapter
: Sets up the VideoPlayerController and starts an analytics session.disposeAdapter
: Removes the VideoPlayerController and ends an analytics session.setPlayerVersion
: Sets the player version for the application.- Various event firing methods: Notify the analytics system of various video events.
Methods
setAdapter
Future<void> setAdapter(VideoPlayerController controller) async
Sets up the VideoPlayerController and starts an analytics session.
Parameters:
controller
: The VideoPlayerController to use for playback analytics.
disposeAdapter
Future<void> disposeAdapter()
Removes the VideoPlayerController and ends an analytics session.
setPlayerVersion
Future<void> setPlayerVersion()
Sets the player version for the application.
fireInit
Future<void> fireInit()
Notifies the analytics platform that playback has been initialized.
fireStart
Future<void> fireStart()
Notifies the analytics platform that playback has started.
firePause
Future<void> firePause()
Notifies the analytics platform that playback has been paused.
fireResume
Future<void> fireResume()
Notifies the analytics platform that playback has been resumed.
fireBufferBegin
Future<void> fireBufferBegin()
Notifies the analytics platform that buffering has begun.
fireBufferEnd
Future<void> fireBufferEnd()
Notifies the analytics platform that buffering has ended.
fireSeekBegin
Future<void> fireSeekBegin()
Notifies the analytics platform that seeking has begun.
fireSeekEnd
Future<void> fireSeekEnd()
Notifies the analytics platform that seeking has ended.
fireStop
Future<void> fireStop()
Notifies the analytics platform that playback has stopped.
fireError
Future<void> fireError()
Notifies the analytics platform that an error has occurred.
customVideoEvent
Future<void> customVideoEvent(String eventName, Map<String, String>? dimensions, Map<String, Double>? values)
Notifies the video analytics system of a custom event.
Parameters:
eventName
: The name of the initial screen, represented as aString
.dimensions
(Optional): AMap<String, String>
containing custom dimensions for the session.values
(Optional): AMap<String, Double>
containing the values for the session.