按照此方案,将用户进度以 Lottie 动画的形式展示——例如,用一个逐渐填充的圆环来表示用户的每日连续打卡天数。你的应用会在自定义元素中以原生 Lottie 视图渲染该动画。
开始前的准备
- 将应用更新至 Adapty Android SDK 4.4 或更高版本。较早的 SDK 版本会为每个自定义元素显示备用内容。
- 配置应用以获取和展示流程。
- 在应用模块中配置 Jetpack Compose。本示例中的动画视图是一个可组合项(composable)。
- 通过 Gradle 将 Lottie for Jetpack Compose 添加到应用中,来源为
com.airbnb.android:lottie-compose。
- 将您的应用更新至 Adapty Android SDK 4.4 或更高版本。早期 SDK 版本会为每个自定义元素显示备用内容。
- 配置您的应用以获取和展示流程。
- 通过 Gradle 从
com.airbnb.android:lottie 将 Lottie 添加到您的应用中。
准备一个 .json 格式的 Lottie 动画,或下载示例文件 streak_ring.json。应用会从头播放动画,并按进度比例停止,例如进度为 50% 时停在中间位置。为了准确呈现进度,动画需要满足以下要求:
- 第一帧不显示任何进度,最后一帧显示完整进度。
- 匀速播放,不带缓动效果。如果动画开始时较慢、后来加速,则播放到一半时显示的进度会少于 50%。
1. 将自定义元素添加到屏幕
在流程与付费墙编辑工具中,向流程屏幕添加自定义元素,并为动画进行如下配置:
- 类型:
lottie_animation。
- ID:
streak_ring。在本示例中,ID 同时也是动画文件的名称。
- 高度:保持默认的固定高度。动画会自动缩放以适应自定义元素的尺寸。
在自定义元素内部,添加一个包含圆环静态图片的图片。当用户使用的应用版本不支持播放动画时,该图片将作为备用内容显示。
2. 将动画文件添加到应用
将动画文件放入 src/main/assets,即应用模块的 assets 文件夹。请将其放在该文件夹的根目录下,不要放在子文件夹中。
文件名(不含 .json 扩展名)必须与自定义元素的 ID 一致,例如 streak_ring 对应 streak_ring.json。
3. 创建动画视图
创建连续打卡的数据模型,以及播放动画的视图。当连续打卡数变化时,你的应用更新该模型。视图读取模型数据,因此当页面打开时,圆环会显示当前的连续打卡数:
// the streak that your app keeps up to date
class StreakStore {
val currentStreak = MutableStateFlow(0) // days in a row
}
@Composable
fun StreakRing(animationFile: String, streakStore: StreakStore) {
val composition by rememberLottieComposition(LottieCompositionSpec.Asset(animationFile))
val streak by streakStore.currentStreak.collectAsState()
// 7 days fill the ring: from 0 for an empty ring to 1 for a full one
val progress = minOf(streak / 7f, 1f)
LottieAnimation(
composition = composition,
modifier = Modifier.fillMaxSize(), // scale the animation to fit the custom element
clipSpec = LottieClipSpec.Progress(0f, progress),
)
}
clipSpec = LottieClipSpec.Progress(0f, progress) 会将圆环从空填充到 progress 指定的位置。如果你的应用已经用 StateFlow 管理连续打卡天数,可以直接用该 StateFlow 替换 StreakStore。
// the streak that your app keeps up to date
public class StreakStore {
public final MutableLiveData<Integer> currentStreak = new MutableLiveData<>(0); // days in a row
}
public class StreakRingView extends LottieAnimationView {
private final StreakStore streakStore;
private final Observer<Integer> streakObserver = streak -> {
// 7 days fill the ring: from 0 for an empty ring to 1 for a full one
float progress = Math.min(streak / 7f, 1f);
setMinAndMaxProgress(0f, progress);
playAnimation();
};
public StreakRingView(Context context, String animationFile, StreakStore streakStore) {
super(context);
this.streakStore = streakStore;
setAnimation(animationFile);
}
@Override
protected void onAttachedToWindow() {
super.onAttachedToWindow();
streakStore.currentStreak.observeForever(streakObserver);
}
@Override
protected void onDetachedFromWindow() {
streakStore.currentStreak.removeObserver(streakObserver);
super.onDetachedFromWindow();
}
}
setMinAndMaxProgress(0f, progress) 和 playAnimation() 会将圆环从空状态填充至 progress 所指定的进度。如果你的应用已通过 LiveData 维护连续打卡天数,可以直接用该 LiveData 替换 StreakStore。
4. 将动画与自定义元素关联
在你的全局 resolver 中,为 streak 模型添加一个属性。然后为 lottie_animation 类型和 streak_ring ID 返回动画视图。高亮行表示需要添加或修改的内容。如果你的应用还没有全局 resolver,可以直接复制完整代码:
class CustomElementsResolver(
context: Context,
private val streakStore: StreakStore,
) : AdaptyCustomElementsResolver {
// the animation files in the assets folder, listed once
private val animationFiles: Set<String> = try {
context.assets.list("").orEmpty().toSet()
} catch (e: IOException) {
emptySet() // no list of files: every Lottie element shows the fallback
}
override fun resolve(type: String, id: String): AdaptyCustomElementContent? =
when (type) {
"lottie_animation" -> {
// the ID names the animation file, such as streak_ring.json
val file = "$id.json"
when {
file !in animationFiles -> null // no file for this ID: show the fallback
id == "streak_ring" ->
AdaptyCustomElementContent.compose { StreakRing(file, streakStore) }
// the other animations of your resolver
else -> null
}
}
// the other Types of your resolver
else -> null
}
}
如果 assets 文件夹中没有对应 ID 的文件,解析器将返回 null,用户将看到备用内容。如果您的解析器已经为每个动画文件返回了一个视图,那么当 ID 不是 streak_ring 时,请返回该视图而不是 null。这样,用户仍然可以看到其他 lottie_animation 自定义元素的动画效果。
public class CustomElementsResolver implements AdaptyCustomElementsResolver {
private final StreakStore streakStore;
// the animation files in the assets folder, listed once
private final Set<String> animationFiles = new HashSet<>();
public CustomElementsResolver(Context context, StreakStore streakStore) {
this.streakStore = streakStore;
try {
String[] files = context.getAssets().list("");
if (files != null) {
animationFiles.addAll(Arrays.asList(files));
}
} catch (IOException e) {
// no list of files: every Lottie element shows the fallback
}
}
@Override
public AdaptyCustomElementContent resolve(String type, String id) {
if (type.equals("lottie_animation")) {
// the ID names the animation file, such as streak_ring.json
String file = id + ".json";
if (!animationFiles.contains(file)) {
return null; // no file for this ID: show the fallback
}
if (id.equals("streak_ring")) {
return AdaptyCustomElementContent.view(
(context, elementContext) -> new StreakRingView(context, file, streakStore)
);
}
// the other animations of your resolver
return null;
}
// the other Types of your resolver
return null;
}
}
如果 assets 文件夹中没有对应该 ID 的文件,解析器会返回 null,用户将看到备用内容。如果你的解析器已经为每个动画文件返回了视图,则在 ID 不是 streak_ring 时返回该视图而非 null。这样,用户仍然可以看到其他 lottie_animation 自定义元素的动画。
创建包含打卡模型的解析器,并将其设置为全局解析器。在应用启动时调用一次 AdaptyUI.setCustomElementsResolver:
class App : Application() {
// the streak model that your app updates
val streakStore = StreakStore()
// keep this instance: a resolver for one flow can reuse it
// lazy: the context isn't attached yet while App is constructed
val customElementsResolver by lazy { CustomElementsResolver(this, streakStore) }
override fun onCreate() {
super.onCreate()
AdaptyUI.setCustomElementsResolver(customElementsResolver)
}
}
public class App extends Application {
// the streak model that your app updates
private final StreakStore streakStore = new StreakStore();
// keep this instance: a resolver for one flow can reuse it
private CustomElementsResolver customElementsResolver;
@Override
public void onCreate() {
super.onCreate();
customElementsResolver = new CustomElementsResolver(this, streakStore);
AdaptyUI.setCustomElementsResolver(customElementsResolver);
}
public StreakStore getStreakStore() {
return streakStore;
}
public CustomElementsResolver getCustomElementsResolver() {
return customElementsResolver;
}
}
5. 在设备上测试
流程与付费墙编辑工具无法运行您的应用代码,因此画布上只显示备用内容。如需预览动画:
- 发布流程。若要查看最新发布版本而非缓存版本,请将设备注册为测试设备。
- 运行包含 resolver 的应用构建版本。将连续天数设为 0 天,打开界面,验证圆环保持空心状态。分别设为 4 天和 7 天后重复操作,验证圆环是否填充至对应值。
如需测试备用内容,请从构建版本中移除动画文件,然后再次打开界面。
要了解为什么显示的是备用内容而不是动画,请参照 Android 指南中在设备上测试部分的说明。