Flutter运动追踪插件motiontag_sdk的使用

概述

MOTIONTAG SDK Flutter Plugin 用于收集手机传感器数据，并以电池高效的方式将其传输到MOTIONTAG后端系统。该SDK支持iOS和Android平台，最低支持版本分别为API 23+（Android）和iOS 12.3+。

1. 安装

首先，在pubspec.yaml文件中添加motiontag_sdk作为依赖项：

dependencies:
  motiontag_sdk: ^latest_version

iOS

在应用委托的didFinishLaunchingWithOptions函数中初始化SDK，然后注册插件。确保在AppDelegate.swift中正确转发handleEventsForBackgroundURLSession调用。参考示例代码。

Android

创建一个Application并在AndroidManifest.xml中注册它。在Application的onCreate回调中调用MotionTagWrapper.initialize()并提供必要的参数。参考示例代码。

为了防止意外行为，建议禁用自动备份或排除SDK相关文件的备份。更多信息请参阅Android MOTIONTAG SDK文档。

2. 权限管理

由于权限管理不在MOTIONTAG SDK范围内，应用程序需要在启动SDK之前获取用户权限。

iOS

在Xcode中添加以下功能：

• 能力 -> 后台模式 -> 位置更新
• Info.plist中添加以下键值对：
  • “Privacy - Motion Usage Description”
  • “Privacy - Location Always & When in Use Description”
  • “Privacy - When in Use Description”

如果使用permission_handler包，请确保在Podfile中添加相应的片段。

Android

在启动SDK前需要请求以下运行时权限：

• android.permission.ACTIVITY_RECOGNITION
• android.permission.ACCESS_FINE_LOCATION
• android.permission.ACCESS_COARSE_LOCATION
• android.permission.ACCESS_BACKGROUND_LOCATION

更多细节请参阅Android MOTIONTAG SDK文档。

3. 使用

MotionTag类是SDK的主要入口点，包含以下公共方法：

import 'package:motiontag_sdk/motiontag.dart';

// 设置用户令牌
await MotionTag.setUserToken('your_jwt_token');

// 开始跟踪
await MotionTag.start();

// 停止跟踪
await MotionTag.stop();

// 获取当前是否正在跟踪
bool isTracking = await MotionTag.isTrackingActive();

// 清除未传输的数据
await MotionTag.clearData();

监听事件

设置观察者函数以接收SDK的相关事件通知：

MotionTag.setObserver((event) {
  if (event is StartedEvent) {
    print('Tracking started');
  } else if (event is StoppedEvent) {
    print('Tracking stopped');
  } else if (event is LocationEvent) {
    print('New location: ${event.location}');
  }
});

4. 用户认证

SDK必须在运行时配置用户特定的JWT令牌。更多信息请参阅Android和iOS SDK文档。

5. 非标准后台进程限制（针对Android）

某些Android OEM厂商实施了非标准的后台进程限制。为确保SDK正常工作，建议开发者引导用户关闭电池优化设置。更多信息请参阅dontkillmyapp.com。

示例Demo

以下是完整的Flutter示例项目结构：

import 'package:flutter/material.dart';
import 'package:motiontag_sdk/motiontag.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  [@override](/user/override)
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'MOTIONTAG SDK Demo',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: MyHomePage(title: 'MOTIONTAG SDK Home Page'),
    );
  }
}

class MyHomePage extends StatefulWidget {
  MyHomePage({Key? key, required this.title}) : super(key: key);

  final String title;

  [@override](/user/override)
  _MyHomePageState createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  bool _isTracking = false;
  String _logMessage = '';

  void _startTracking() async {
    try {
      await MotionTag.setUserToken('your_jwt_token');
      await MotionTag.start();
      setState(() {
        _isTracking = true;
      });
      MotionTag.setObserver((event) {
        setState(() {
          _logMessage = event.toString();
        });
      });
    } catch (e) {
      setState(() {
        _logMessage = 'Error starting tracking: $e';
      });
    }
  }

  void _stopTracking() async {
    try {
      await MotionTag.stop();
      setState(() {
        _isTracking = false;
      });
    } catch (e) {
      setState(() {
        _logMessage = 'Error stopping tracking: $e';
      });
    }
  }

  [@override](/user/override)
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text(widget.title),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: <Widget>[
            ElevatedButton(
              onPressed: _isTracking ? null : _startTracking,
              child: Text('Start Tracking'),
            ),
            ElevatedButton(
              onPressed: _isTracking ? _stopTracking : null,
              child: Text('Stop Tracking'),
            ),
            Text(_logMessage),
          ],
        ),
      ),
    );
  }
}