roadsdata_flutter_sdk

Description:

roadsdata flutter sdk

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
copied to clipboard
Then, run the following command to install the package:
flutter pub get
copied to clipboard
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',
);
copied to clipboard
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());
}
copied to clipboard
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);
}
}
copied to clipboard
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');
}
};
copied to clipboard
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/