roadsdata_flutter_sdk 1.2.0

A flutter package for an easy implementation of RoadsData ads in your Flutter apps.

Introduction

The Flutter Roadsdata SDK provides an easy and efficient way to integrate Roadsdata services into your Flutter application. This SDK simplifies the process of handling Roadsdata's ads integration, making it seamless to incorporate Roadsdata's functionalities within your app's navigation and user experience.

Table of Contents

• Installation
• Usage
• Integration
• Handling Deep Links / Testing feature
• Handling Extras
• Troubleshooting
• Additional Information

Installation

To use the Flutter Roadsdata SDK, you need to first add it as a dependency in your Flutter project. Add the following line to your pubspec.yaml file under dependencies:

flutter_roadsdata: latest_version

Then, run the following command to install the package:

flutter pub get

Usage

To initialize the SDK, add the following configuration in your Flutter app, typically inside the main.dart or within the initialization logic of your application:

FlutterRoadsdata.init(
  host: 'YOUR_HOST',
  clientId: 'YOUR_CLIENT_ID',
  accessToken: 'YOUR_ACCESS_TOKEN',
);

Ensure you replace YOUR_HOST, YOUR_CLIENT_ID, and YOUR_ACCESS_TOKEN with your actual Roadsdata host, client ID, and access token.

Integration

Wrap your main app widget with RoadsdataWrapper to ensure Roadsdata functionalities are available throughout your app:

@Override
Widget build(BuildContext context) {
  return const RoadsdataWrapper(child: FlutterRoadsdataExampleApp());
}

Handling Deep Links / Test feature

• Configuring the deeplink handler is required for the deeplink click action to work.

• Configuring deeplinks callbacks is required in order to make test ad feature working.

To handle deep links and integrate them with your app's navigation, follow the example provided below and adapt it to your app's need

import 'dart:async';
import 'package:flutter/material.dart';
import 'package:flutter/services.dart' show PlatformException;
import 'package:roadsdata_flutter_sdk/flutter_roadsdata.dart';
import 'package:uni_links/uni_links.dart';
import 'package:flutter_roadsdata_example/src/navigation_router.dart';

bool _initialUriIsHandled = false;

class FlutterRoadsdataExampleApp extends StatefulWidget {
  @override
  State<FlutterRoadsdataExampleApp> createState() => _FlutterRoadsdataExampleAppState();
}

class _FlutterRoadsdataExampleAppState extends State<FlutterRoadsdataExampleApp> {
  StreamSubscription? _streamSubscription;

  @override
  void initState() {
    super.initState();
    _handleIncomingLink();
    _handleInitialUri();
    // Setup deeplink handler
    FlutterRoadsdata.instance!.deeplinkHandler = (String uriString) {
      // implement your navigation solution here
      goRouter.go(Uri.parse(uriString).path);
    };
  }

    Future<void> _handleInitialUri() async {
    if (!_initialUriIsHandled) {
      _initialUriIsHandled = true;
      try {
        final Uri? uri = await getInitialUri();
        if (uri!= null) {
        if (!mounted) return;
          print('got initial uri: $uri');

          // Get the service
          final adService = RoadsdataWrapper.of(context);
          // Extract the testCode from query parameter
          String? testCode = uri.queryParameters['rd_test_uuid'];
          // use the fetch test ad functionality. 
          adService.fetchTestAd(testCode!);

          // then navigate to the deeplink path. There you'll find the container with the test ad visible.
          goRouter.go(uri.path);
        } else {
          print('no initial uri');
        }

      } on PlatformException {
        // Platform messages may fail but we ignore the exception
        print('failed to get initial uri');
      } on FormatException catch (err) {
        if (!mounted) return;
        print('malformed initial uri');
      }
    }
  }

  Future<void> _handleIncomingLink() async {
    _streamSubscription = linkStream.listen((String? link) {
      if (!mounted) return;
      if (link != null) {
        Uri uri = Uri.parse(link);

        // See _handleInitialUri for the basic explanation
        final adService = RoadsdataWrapper.of(context);

        String? testCode = uri.queryParameters['rd_test_uuid'];
        adService.fetchTestAd(testCode!);

        goRouter.go(uri.path);
      }
    }, onError: (err) {
      // Handle exception by warning the user their action did not succeed
      print(err.toString());
    });
  }

  @override
  void dispose() {
    _streamSubscription?.cancel();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp.router(routerConfig: goRouter);
  }
}

Replace FlutterRoadsdataExampleApp and goRouter with your application and router instances respectively.

Handling Extras

In addition to Roadsdata's basic tracking of all impression, click and close events, the Roadsdata SDK allows you to integrate third-party services such as Google Analytics and Piwik.

From the RoadsData platform it is possible to enter and configure some specific parameters such as 'action', 'category' and 'name' of piwik.

Register a callback function via the extraActionsHandler setter. RoadsData SDK will take care of calling it with the data set via the web platform.

Example:

FlutterRoadsdata.instance!.extraActionsHandler = (String type, Map<String, dynamic> payload) {
  switch (type) {
    case 'piwik-event':
      await FlutterPiwikPro.sharedInstance.trackCustomEvent(
        action: payload['eventAction'],
        category: payload['eventCategory'],
        name: payload['eventName'],
      );
    case 'analytics-event':
      await FirebaseAnalytics.instance.logEvent(
          name: payload['name'],
          parameters: payload['params'],
      );
    case 'analytics-screenview':
      await FirebaseAnalytics.instance.logEvent(
        name: 'screen_view',
        parameters: {
          'firebase_screen': payload['screenName'],
          'firebase_screen_class': payload['screenClass'],
        },
      );
    default:
      debugPrint('Unknown extra event of type $type');
  }
};

Troubleshooting

• If you encounter any issues with the SDK initialization, make sure you have correctly set your host, clientId, and accessToken.
• For issues related to deep links handling, ensure your app's navigation setup is correctly configured to handle incoming URIs.

Additional information

If you want to know more about Roadsdata, visit https://roadsdata.it/