AppUnion Flutter SDK

应用互相推荐联盟客户端。接入方用自己的 app_id 初始化后，即可展示推荐列表。

对外只用 initialize / fetchInfo / canShow / show。入口 UI 由接入方自己画。

限制

  • 仅支持 Android、鸿蒙。iOS / 桌面 / Web 上 canShow() 为 false，show() / fetchInfo() 不发请求、不展示 UI。
  • 同端互推：platform 由 SDK 按当前运行端探测（android / harmony），接口里鸿蒙仍传 harmonyos，宿主不能覆盖。
  • 未配置的端不要请求：用 enabledPlatforms 声明本应用已开通的端，只能包含 Android、鸿蒙。
  • 自己隐藏互推：GET /v1/info 返回 hidden: true 是 200，不是错误。此时不渲染、不请求 recommend、不换一批、不报曝光。

安装

dependencies:
  appunion_flutter: ^0.0.1

初始化

import 'package:appunion_flutter/appunion_flutter.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await AppUnion.instance.initialize(const AppUnionConfig(
    appId: '<你的 app_id>',
    enabledPlatforms: {
      AppUnionPlatform.android,
      AppUnionPlatform.harmony,
    },
    // 默认 true：弹窗底部显示「不再显示」
    // showDisableEntry: false,
  ));
  runApp(const MyApp());
}

不要 API Key，不要自建后端转发。客户端直连 https://appunion.chiyoushu.com。

AppUnionConfig 常用项：

字段 默认 说明
appId 必填 本应用在 AppUnion 申请的 ID，只出现在查询参数里
baseUrl https://appunion.chiyoushu.com 开放接口根地址
enabledPlatforms Android + 鸿蒙 本应用已开通的端
showDisableEntry true 是否显示底部「不再显示」
debug false 打印网络日志；桌面端按 enabledPlatforms 回落到 Android。正式接入不要开

本地用 Mac 跑 example 时可设 debug: true。正式接入不要开。

展示

入口是否展示完全由接入方控制。fetchInfo() 每次请求网络，不缓存。

try {
  if (AppUnion.instance.isLocallyDisabled) {
    return;
  }
  final info = await AppUnion.instance.fetchInfo();
  if (info == null || info.hidden) {
    // 非 Android/鸿蒙、未配置端、或开发者关闭了展示
    return;
  }
  // 用 info.name、info.subtitle、info.logoUrl 画入口
} on AppUnionException {
  // 网络或鉴权失败，藏入口
}

// 点击入口
await AppUnion.instance.show(context, onDisabled: () {
  // 用户点了「不再显示」，接入方自己摘掉入口
  // showDisableEntry 为 false 时不会出现该按钮，也不会回调
});

也可以用 canShow() 做一次快捷判断（平台 + 本地关闭 + hidden），再决定是否画入口。

入口图标资源：

SvgPicture.asset(
  AppUnionAssets.entryIcon,
  package: AppUnionAssets.package,
)

弹窗行为

  • 标题用 info.name，没有则回落到「群星计划」。
  • notice 用 info.description，没有则回落到「来自伙伴精选应用，共建优质生态」。文案里的 --- 会按换行处理。
  • 右上角是刷新图标和关闭。刷新只请求一次 recommend。
  • 卡片进入可视区域后再报曝光，不会一进页批量报。
  • 点应用行或「获取」进入详情；详情里点下载再报点击并跳转。应用商店链接按端打开：Android market://details?id=<package_name>，鸿蒙 store://appgallery.huawei.com/app/detail?id=<package_name>。官网等 http(s) 仍打开服务端地址。
  • showDisableEntry 为 true 时，底部有「不再显示」，会本地关闭入口。

接口约定

  1. GET /v1/info?app_id=<本应用>：联盟品牌、hidden、description。没有 platform
  2. GET /v1/apps/recommend?app_id=<本应用>&platform=<当前端>：卡片列表。不要传 limit，不要截断
  3. GET /v1/apps/<id>?app_id=<本应用>&platform=<当前端>：点应用行或「获取」后拉详情
  4. POST /v1/events/impressions?app_id=<本应用>：platform 在 body 里。卡片进入可视区域后再报
  5. POST /v1/events/clicks?app_id=<本应用>：platform 在 body 里。详情里点下载后再报，然后跳转

查询参数里的 app_id 是本应用；曝光 / 点击请求体里的 app_id 是列表里被展示或下载的应用。

常见错误

状态 code 含义
401 unauthorized app_id 无效
403 app_not_approved / app_paused_by_ops 已拒绝或运营暂停
404 target_not_found 目标不存在
429 rate_limited 频率限制

hidden: true 不是错误。

Libraries

appunion_flutter