Flutter用户消息管理插件user_messaging_platform的使用

插件简介

user_messaging_platform 是一个Flutter插件，它提供了用于Google Funding Choices的用户消息管理平台（User Messaging Platform, UMP）SDK的Dart API。UMP SDK是一个同意管理平台（Consent Management Platform, CMP），帮助开发者获取和管理用户的同意信息。

此外，还可以查看iabtcf_consent_info包来读取通过CMP SDK（如UMP）提供的TCF同意信息。

如果你正在寻找一个数据库解决方案，可以看看cbl，它为独立的Dart和Flutter带来了Couchbase Lite的支持，包括全文搜索、表达式查询、数据同步和更改通知等功能。

Setup

Android

App ID

1. 通过帮助中心说明获取你的APP ID。
2. 将你的App ID添加到AndroidManifest.xml中：

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.yourapp">

    <application>
        <meta-data
            android:name="com.google.android.gms.ads.APPLICATION_ID"
            android:value="YOUR-APP-ID"/>
        ...
    </application>

</manifest>

更多信息请参阅Android UMP SDK快速入门指南。

iOS

App ID

1. 通过帮助中心说明获取你的APP ID。
2. 将你的App ID添加到Info.plist中：

<key>GADApplicationIdentifier</key>
<string>YOUR-APP-ID</string>

App Tracking Transparency

如果你想使用App Tracking Transparency框架：

1. 在Info.plist中添加NSUserTrackingUsageDescription：

<key>NSUserTrackingUsageDescription</key>
<string>此标识符将用于向您提供个性化广告。</string>

1. 在Targets -> Runner -> Frameworks, Libraries, and Embedded Content中链接Runner目标到AppTrackingTransparency。

更多信息请参阅iOS UMP SDK快速入门指南。

Usage

以下是一个基本的使用示例，展示了如何更新同意信息并在需要时显示同意表单：

void updateConsent() async {
  // 确保继续使用最新的同意信息。
  var info = await UserMessagingPlatform.instance.requestConsentInfoUpdate();

  // 如果同意是必需的，则显示同意表单。
  if (info.consentStatus == ConsentStatus.required) {
    // `showConsentForm`返回同意表单关闭后的最新同意信息。
    info = await UserMessagingPlatform.instance.showConsentForm();
  }
}

iOS: App Tracking Transparency

你可以让UMP SDK处理ATT权限请求。如果你想自行决定何时显示权限请求，可以通过此插件检查TrackingAuthorizationStatus并调用requestTrackingAuthorization：

void showATTPermissionRequest() async {
  final status = await UserMessagingPlatform.instance.getTrackingAuthorizationStatus();

  if (status == TrackingAuthorizationStatus.notDetermined) {
    await UserMessagingPlatform.instance.requestTrackingAuthorization();
  }
}

Example

下面是一个完整的示例应用程序，演示了如何配置和使用user_messaging_platform插件：

import 'package:flutter/material.dart';
import 'package:user_messaging_platform/user_messaging_platform.dart';

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

class App extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      debugShowCheckedModeBanner: false,
      theme: ThemeData.light(),
      darkTheme: ThemeData.dark(),
      home: HomePage(),
    );
  }
}

class HomePage extends StatefulWidget {
  @override
  _HomePageState createState() => _HomePageState();
}

class _HomePageState extends State<HomePage> {
  final _ump = UserMessagingPlatform.instance;
  TrackingAuthorizationStatus? _trackingAuthorizationStatus;
  ConsentInformation? _consentInformation;

  bool _tagAsUnderAgeOfConsent = false;
  bool _debugSettings = false;
  String? _testDeviceId;
  DebugGeography _debugGeography = DebugGeography.disabled;

  @override
  void initState() {
    if (defaultTargetPlatform == TargetPlatform.iOS) {
      _loadTrackingAuthorizationStatus();
    }
    _loadConsentInfo();
    super.initState();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: SafeArea(
        child: Padding(
          padding: const EdgeInsets.all(16.0),
          child: Column(
            crossAxisAlignment: CrossAxisAlignment.start,
            children: [
              Text(
                'User Messaging Platform',
                style: Theme.of(context).textTheme.headline5,
              ),
              SizedBox(height: 16),
              if (_consentInformation == null)
                LinearProgressIndicator()
              else
                Text(_consentInformation.toString()),
              SizedBox(height: 16),
              CheckboxListTile(
                title: Text('Tag as under age of consent'),
                value: _tagAsUnderAgeOfConsent,
                onChanged: (value) {
                  setState(() {
                    _tagAsUnderAgeOfConsent = value!;
                  });
                },
              ),
              _buildDebugSettings(context),
              SizedBox(height: 16),
              ElevatedButton(
                child: Text('Request consent info update'),
                onPressed: _requestConsentInfoUpdate,
              ),
              SizedBox(height: 16),
              ElevatedButton(
                child: Text('Reset consent info'),
                onPressed: _resetConsentInfo,
              ),
              SizedBox(height: 16),
              ElevatedButton(
                child: Text('Show consent form'),
                onPressed: _showConsentForm,
              ),
              if (defaultTargetPlatform == TargetPlatform.iOS) ...[
                SizedBox(height: 32),
                Text(
                  'App Tracking Transparency',
                  style: Theme.of(context).textTheme.headline5,
                ),
                SizedBox(height: 16),
                if (_trackingAuthorizationStatus == null)
                  LinearProgressIndicator()
                else
                  Text('$_trackingAuthorizationStatus'),
                SizedBox(height: 16),
                ElevatedButton(
                  child: Text('Request ATT permission'),
                  onPressed: _requestATTPermission,
                ),
              ],
            ],
          ),
        ),
      ),
    );
  }

  Future<void> _loadTrackingAuthorizationStatus() {
    return _ump.getTrackingAuthorizationStatus().then((status) {
      setState(() {
        _trackingAuthorizationStatus = status;
      });
    });
  }

  Future<void> _requestATTPermission() {
    return _ump.requestTrackingAuthorization().then((status) {
      setState(() {
        _trackingAuthorizationStatus = status;
      });
    });
  }

  Future<void> _loadConsentInfo() {
    return _ump.getConsentInfo().then((info) {
      setState(() {
        _consentInformation = info;
      });
    });
  }

  Future<void> _requestConsentInfoUpdate() {
    return _ump
        .requestConsentInfoUpdate(_buildConsentRequestParameters())
        .then((info) {
      setState(() {
        _consentInformation = info;
      });
    });
  }

  Future<void> _resetConsentInfo() async {
    await _ump.resetConsentInfo();
    await _loadConsentInfo();
  }

  Future<void> _showConsentForm() {
    return _ump.showConsentForm().then((info) {
      setState(() {
        _consentInformation = info;
      });
    });
  }

  ConsentRequestParameters _buildConsentRequestParameters() {
    final parameters = ConsentRequestParameters(
      tagForUnderAgeOfConsent: _tagAsUnderAgeOfConsent,
      debugSettings: _debugSettings
          ? ConsentDebugSettings(
              geography: _debugGeography,
              testDeviceIds: _testDeviceId == null ? null : [_testDeviceId!],
            )
          : null,
    );
    return parameters;
  }

  Widget _buildDebugSettings(BuildContext context) {
    return Column(
      mainAxisSize: MainAxisSize.min,
      children: [
        CheckboxListTile(
          title: Text('Debug Settings'),
          value: _debugSettings,
          onChanged: (debugSettings) {
            setState(() {
              _debugSettings = debugSettings!;
            });
          },
        ),
        if (_debugSettings) ...[
          TextFormField(
            initialValue: _testDeviceId,
            onChanged: (testDeviceId) {
              _testDeviceId = testDeviceId.trim();
            },
            decoration: InputDecoration(
              filled: true,
              labelText: 'Test Device Id',
            ),
          ),
          ListTile(
            title: Text('Geography'),
            trailing: DropdownButton<DebugGeography>(
              value: _debugGeography,
              onChanged: (debugGeography) {
                setState(() {
                  _debugGeography = debugGeography!;
                });
              },
              items: [
                DropdownMenuItem(
                  child: Text('Disabled'),
                  value: DebugGeography.disabled,
                ),
                DropdownMenuItem(
                  child: Text('Not EEA'),
                  value: DebugGeography.notEEA,
                ),
                DropdownMenuItem(
                  child: Text('EEA'),
                  value: DebugGeography.EEA,
                ),
              ],
            ),
          )
        ]
      ],
    );
  }
}

这个示例应用程序展示了如何在Flutter应用中集成user_messaging_platform插件，包括请求同意信息更新、显示同意表单以及处理iOS的App Tracking Transparency权限请求。