NPAW Plugin for Flutter

Table of contents

• Integration guide

  • 1. Install the library as a dependency
  • 2. Integrate the library into your code

• Plugin Modules

  • 1. Options
  • 2. AppAnalytics
  • 3. VideoAnalytics

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 the video_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 the plugin.options.setContentTitle('Title of my content') method
• (3): The contentResourse URL using the plugin.options.setContentResource('http://resource-url.com') method.
• (4): The playerVersion of the current player. If needed, check on the pubspeck.lock to find it.
• (5): The VideoPlayerController of the player used on the screen using the plugin.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, AppAnalyticsand 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 a String.

setUsername

Future<void> setUsername(String username)

Sets the username for the user.

Parameters:

• username: The username for the user, represented as a String.

setUserType

Future<void> setUserType(String userType)

Sets the user type for the user.

Parameters:

• userType: The user type for the user, represented as a String.

setUserEmail

Future<void> setUserEmail(String userEmail)

Sets the user email for the user.

Parameters:

• userEmail: The user email for the user, represented as a String.

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 a String.

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 a String.

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 a String.

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 a String.

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 a String.

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 a String.

setDeviceIsAnonymous

Future<void> setDeviceIsAnonymous(bool deviceIsAnonymous)

Sets whether the user's device is anonymous or not.

Parameters:

• deviceIsAnonymous: A bool 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 a String.

setContentIsLive

Future<void> setContentIsLive(bool contentIsLive)

Sets whether the content is live or not.

Parameters:

• contentIsLive: A bool 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 a String.

setProgram

Future<void> setProgram(String program)

Sets the program for the application.

Parameters:

• program: The program for the application, represented as a String.

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 an int.

setContentThroughput

Future<void> setContentThroughput(int contentThroughput)

Sets the content throughput for the application.

Parameters:

• contentThroughput: The content throughput for the application, represented as an int.

setContentRendition

Future<void> setContentRendition(String contentRendition)

Sets the content rendition for the application.

Parameters:

• contentRendition: The content rendition for the application, represented as a String.

setContentLanguage

Future<void> setContentLanguage(String contentLanguage)

Sets the content language for the application.

Parameters:

• contentLanguage: The content language for the application, represented as a String.

setAppName

Future<void> setAppName(String appName)

Sets the application name.

Parameters:

• appName: The application name, represented as a String.

setAppReleaseVersion

Future<void> setAppReleaseVersion(String appReleaseVersion)

Sets the application release version.

Parameters:

• appReleaseVersion: The application release version, represented as a String.

setCustomDimension1

Future<void> setCustomDimension1(String customDimension1)

Sets custom dimension 1.

Parameters:

• customDimension1: The custom dimension 1 value, represented as a String.

setCustomDimension2

Future<void> setCustomDimension2(String customDimension2)

Sets custom dimension 2.

Parameters:

• customDimension2: The custom dimension 2 value, represented as a String.

setCustomDimension3

Future<void> setCustomDimension3(String customDimension3)

Sets custom dimension 3.

Parameters:

• customDimension3: The custom dimension 3 value, represented as a String.

setCustomDimension4

Future<void> setCustomDimension4(String customDimension4)

Sets custom dimension 4.

Parameters:

• customDimension4: The custom dimension 4 value, represented as a String.

setCustomDimension5

Future<void> setCustomDimension5(String customDimension5)

Sets custom dimension 5.

Parameters:

• customDimension5: The custom dimension 5 value, represented as a String.

setCustomDimension6

Future<void> setCustomDimension6(String customDimension6)

Sets custom dimension 6.

Parameters:

• customDimension6: The custom dimension 6 value, represented as a String.

setCustomDimension7

Future<void> setCustomDimension7(String customDimension7)

Sets custom dimension 7.

Parameters:

• customDimension7: The custom dimension 7 value, represented as a String.

setCustomDimension8

Future<void> setCustomDimension8(String customDimension8)

Sets custom dimension 8.

Parameters:

• customDimension8: The custom dimension 8 value, represented as a String.

setCustomDimension9

Future<void> setCustomDimension9(String customDimension9)

Sets custom dimension 9.

Parameters:

• customDimension9: The custom dimension 9 value, represented as a String.

setCustomDimension10

Future<void> setCustomDimension10(String customDimension10)

Sets custom dimension 10.

Parameters:

• customDimension10: The custom dimension 10 value, represented as a String.

setCustomDimension11

Future<void> setCustomDimension11(String customDimension11)

Sets custom dimension 11.

Parameters:

• customDimension11: The custom dimension 11 value, represented as a String.

setCustomDimension12

Future<void> setCustomDimension12(String customDimension12)

Sets custom dimension 12.

Parameters:

• customDimension12: The custom dimension 12 value, represented as a String.

setCustomDimension13

Future<void> setCustomDimension13(String customDimension13)

Sets custom dimension 13.

Parameters:

• customDimension13: The custom dimension 13 value, represented as a String.

setCustomDimension14

Future<void> setCustomDimension14(String customDimension14)

Sets custom dimension 14.

Parameters:

• customDimension14: The custom dimension 14 value, represented as a String.

setCustomDimension15

Future<void> setCustomDimension15(String customDimension15)

Sets custom dimension 15.

Parameters:

• customDimension15: The custom dimension 15 value, represented as a String.

setCustomDimension16

Future<void> setCustomDimension16(String customDimension16)

Sets custom dimension 16.

Parameters:

• customDimension16: The custom dimension 16 value, represented as a String.

setCustomDimension17

Future<void> setCustomDimension17(String customDimension17)

Sets custom dimension 17.

Parameters:

• customDimension17: The custom dimension 17 value, represented as a String.

setCustomDimension18

Future<void> setCustomDimension18(String customDimension18)

Sets custom dimension 18.

Parameters:

• customDimension18: The custom dimension 18 value, represented as a String.

setCustomDimension19

Future<void> setCustomDimension19(String customDimension19)

Sets custom dimension 19.

Parameters:

• customDimension19: The custom dimension 19 value, represented as a String.

setCustomDimension20

Future<void> setCustomDimension20(String customDimension20)

Sets custom dimension 20.

Parameters:

• customDimension20: The custom dimension 20 value, represented as a String.

setContentCdn

Future<void> setContentCdn(String contentCdn)

Sets the content CDN for the application.

Parameters:

• contentCdn: The content CDN for the application, represented as a String.

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 a bool.

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 a bool.

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 a String.

setContentPackage

Future<void> setContentPackage(String contentPackage)

Sets the content package for the application.

Parameters:

• contentPackage: The content package for the application, represented as a String.

setContentSaga

Future<void> setContentSaga(String contentSaga)

Sets the content saga for the application.

Parameters:

• contentSaga: The content saga for the application, represented as a String.

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 a String.

setContentSeason

Future<void> setContentSeason(String contentSeason)

Sets the content season for the application.

Parameters:

• contentSeason: The content season for the application, represented as a String.

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 a String.

setContentChannel

Future<void> setContentChannel(String contentChannel)

Sets the content channel for the application.

Parameters:

• contentChannel: The content channel for the application, represented as a String.

setContentId

Future<void> setContentId(String contentId)

Sets the content ID for the application.

Parameters:

• contentId: The content ID for the application, represented as a String.

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 a String.

setContentType

Future<void> setContentType(String contentType)

Sets the content type for the application.

Parameters:

• contentType: The content type for the application, represented as a String.

setContentGenre

Future<void> setContentGenre(String contentGenre)

Sets the content genre for the application.

Parameters:

• contentGenre: The content genre for the application, represented as a String.

setContentSubtitles

Future<void> setContentSubtitles(String contentSubtitles)

Sets the content subtitles for the application.

Parameters:

• contentSubtitles: The content subtitles for the application, represented as a String.

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 a String.

setContentDrm

Future<void> setContentDrm(String contentDrm)

Sets the content DRM for the application.

Parameters:

• contentDrm: The content DRM for the application, represented as a String.

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 a String.
• dimensions (Optional): A Map<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 a String.

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 a String.
• dimensions (Optional): A Map<String, String> containing custom dimensions for the session.
• values (Optional): A Map<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 a String.
• dimensions (Optional): A Map<String, String> containing custom dimensions for the session.
• values (Optional): A Map<String, Double> containing the values for the session.

Libraries

app_analytics

constants

lib_npaw_plugin_flutter

lib_npaw_plugin_flutter_method_channel

lib_npaw_plugin_flutter_platform_interface

options

video_analytics