Flutter数据获取插件roadsdata_flutter_sdk的使用

Flutter数据获取插件roadsdata_flutter_sdk的使用

引言

Flutter Roadsdata SDK 提供了一种简单且高效的方法来将 Roadsdata 服务集成到您的 Flutter 应用程序中。此 SDK 简化了处理 Roadsdata 的广告集成过程，使其无缝地融入您应用的导航和用户体验。

目录

• 安装
• 使用
• 集成
• 处理深层链接
• 处理附加功能
• 故障排除
• 附加信息

安装

要使用 Flutter Roadsdata SDK，您需要首先将其作为依赖项添加到您的 Flutter 项目中。在您的 pubspec.yaml 文件的 dependencies 下添加以下行：

flutter_roadsdata: latest_version

然后，运行以下命令以安装该包：

flutter pub get

使用

要初始化 SDK，请在您的 Flutter 应用程序中添加以下配置，通常在 main.dart 或应用程序初始化逻辑中：

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

确保将 YOUR_HOST、YOUR_CLIENT_ID 和 YOUR_ACCESS_TOKEN 替换为您实际的 Roadsdata 主机、客户端 ID 和访问令牌。

集成

为了确保在整个应用程序中可用 Roadsdata 功能，将您的主应用小部件包装在 RoadsdataWrapper 中：

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

处理深层链接

配置深层链接处理器是使深层链接点击操作正常工作的必要步骤。配置深层链接回调是为了让测试广告功能工作。

要处理深层链接并将其与应用的导航集成，遵循以下示例并根据您的应用需求进行调整：

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();
    // 设置深层链接处理器
    FlutterRoadsdata.instance!.deeplinkHandler = (String uriString) {
      // 实现您的导航解决方案
      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');

          // 获取服务
          final adService = RoadsdataWrapper.of(context);
          // 从查询参数中提取测试码
          String? testCode = uri.queryParameters['rd_test_uuid'];
          // 使用测试广告功能
          adService.fetchTestAd(testCode!);

          // 导航到深层链接路径。在那里，您会看到包含测试广告的容器。
          goRouter.go(uri.path);
        } else {
          print('no initial uri');
        }

      } on PlatformException {
        // 平台消息可能会失败，但我们忽略异常
        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);

        // 参见_handleInitialUri的基本解释
        final adService = RoadsdataWrapper.of(context);

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

        goRouter.go(uri.path);
      }
    }, onError: (err) {
      // 处理异常，警告用户其操作未成功
      print(err.toString());
    });
  }

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

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

将 FlutterRoadsdataExampleApp 和 goRouter 替换为您的应用和路由实例。

处理附加功能

除了 Roadsdata 基本跟踪所有印象、点击和关闭事件外，Roadsdata SDK 还允许您集成第三方服务，如 Google Analytics 和 Piwik。

从 RoadsData 平台可以输入和配置一些特定参数，例如 'action', 'category' 和 'name' of Piwik。

通过 extraActionsHandler 注册一个回调函数。RoadsData SDK 将使用通过 Web 平台设置的数据调用它。

示例：

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');
  }
};

故障排除

• 如果遇到 SDK 初始化问题，请确保正确设置了您的主机、客户端 ID 和访问令牌。
• 对于深层链接处理问题，请确保您的应用程序导航设置正确配置以处理传入的 URI。

附加信息

如果您想了解更多关于 Roadsdata 的信息，请访问 https://roadsdata.it/