Download the PHP package lemoba/mobile-monetization without Composer

Mobile Monetization for Laravel

Laravel 扩展包，用于移动端短剧/内容应用常见的后端验证能力：

• iOS Sign in with Apple 登录 token 验证
• Android Google 登录 ID token 验证
• iOS App Store / Android Google Play 内购验证
• Unity LevelPlay 激励广告 S2S 回调验签
• Firebase Cloud Messaging iOS / Android 消息推送

本包只做「可信验证、签名校验、接口封装、结果归一化、推送发送」，不创建数据表，不写数据库，不给用户加金币，不开通 VIP，不解锁视频。订单幂等、金币流水、会员权益、短剧解锁、推送 token 保存等业务逻辑全部由调用方完成。

安装

通过 Composer 安装：

发布配置：

环境变量

配置文件会按职责发布到主项目：

路由

本包不注册任何默认路由，由调用方在主项目中自行定义路由和控制器。示例：

缓存

JWKS、公钥集合、Google Play OAuth token、App Store Server API bearer token、FCM OAuth token 都会走 Laravel Cache，并默认使用 Redis：

调用方可以改 store 使用任意 Laravel cache store，但生产环境建议 Redis。

登录验证

Apple：

Google：

返回字段包含：

调用方应该用 provider + provider_user_id 去绑定或创建自己的用户。

provider_user_id 来自 Apple / Google ID token 的 sub 字段。本包会强制校验 sub，如果 token 中没有 sub 会直接抛出异常，不会返回空的 provider_user_id。

支付验证

iOS App Store：

iOS App Store 订阅优惠签名：

applePromotionalOfferSignature() 参数：

• productIdentifier：App Store Connect 中的订阅商品 ID，例如 vip_month。
• subscriptionOfferId：App Store Connect 中配置的 promotional offer identifier，例如 intro_month_50。
• appAccountToken：与客户端购买时传入的 app account token 保持一致；如果客户端不传，可以留空。
• nonce：可选，不传时服务端自动生成 UUID。
• timestamp：可选，毫秒时间戳，不传时服务端自动生成。

客户端按 Apple StoreKit API 使用返回字段即可：

如配置了 APPLE_PROMOTIONAL_OFFER_KEY_ID / APPLE_PROMOTIONAL_OFFER_PRIVATE_KEY_PATH，会优先使用订阅优惠专用密钥；否则回退到 APPLE_KEY_ID / APPLE_PRIVATE_KEY_PATH。

新版 StoreKit 2 promotional offer compact JWS：

applePromotionalOfferJws() 参数：

• productId：App Store Connect 中的订阅商品 ID。
• offerIdentifier：App Store Connect 中配置的 promotional offer identifier。
• transactionId：可选，通常传原始订阅交易 ID。
• nonce：可选，不传时服务端自动生成 UUID。

Android Google Play 一次性消耗商品：

一次性消耗商品适合金币、钻石、体力、道具包等可以反复购买的商品。服务端必须先请求 Google Play Developer API 验证 purchaseToken，验单成功后还要调用 Google 的 consume 接口；否则 Google Play 侧该购买 token 未被消费，同一个商品可能无法再次购买。

如果客户端把业务订单号放进 Google Billing 的 obfuscatedExternalProfileId，服务端可以先只用 purchaseToken 解析订单号，再查询自己的订单表判断这笔订单是订阅还是一次性消耗商品：

parseGoogleOrderNo() 返回：

推荐使用 verifyAndConsumeGoogleProduct() 一次完成“验单 + 消费”：

如果客户端没有单独上传 product_id，也可以只传 purchaseToken。服务端会调用 Google Play purchases.productsv2 查询购买信息，并从返回的 productLineItem[0].productId 补出商品 ID：

verifyAndConsumeGoogleProduct() 的行为：

• 先调用 Google Play Developer API 验证一次性商品 purchaseToken。
• 只有 Google 返回已购买状态时，才会继续调用 consumeGoogleProduct()。
• 返回 VerifiedPurchase，调用方仍然要按 transaction_id 做业务幂等。
• consume 只代表释放 Google Play 侧的再次购买能力，不代表你的业务已经发货；发货仍然由调用方自己完成。

如果业务需要把“验单、入库、发货、消费”拆成自己的事务流程，也可以手动调用：

一次性商品注意事项：

• 消耗型商品必须 consume，不需要订阅那种续期状态维护。
• consumeGoogleProduct() 只用于一次性商品，不用于订阅。
• 不要只信任客户端返回结果；服务端必须使用 purchaseToken 请求 Google 接口验单。
• 发货前要用 transaction_id 或订单号建唯一索引，避免客户端重复请求导致重复发货。
• 如果使用手动流程，建议只有在本地订单和发货幂等逻辑已经处理完成后，再调用 consume。

Android Google Play VIP 周/月/年订阅：

订阅适合 VIP 周卡、月卡、年卡等周期性权益。订阅不是消耗品，不需要也不能调用 consumeGoogleProduct()。服务端要做的是验证 purchaseToken，读取 Google 返回的订阅状态和到期时间，然后更新自己系统里的会员权益。

订阅返回的 VerifiedPurchase 里，常用字段包括：

• product_id：Google Play Console 中的订阅商品 ID。
• transaction_id：Google 返回的最新订单 ID；没有时回退到 purchaseToken。
• original_transaction_id：关联购买 token 或最新订单 ID；可用于串联同一订阅链路。
• valid：当前订阅是否处于可用状态。
• active()：valid 为真，且未过期时返回真。
• expires_at_ms：当前订阅周期到期时间，毫秒时间戳。
• raw：Google Play Developer API 的完整响应。
• external_profile_id：客户端放入 obfuscatedExternalProfileId 的业务订单号。

订阅注意事项：

• verifyGoogleSubscription() 的 productId 就是 Google Play Console 里的订阅商品 ID；旧的 subscriptionId 命名参数仍然可用。
• 订阅不调用 consumeGoogleProduct()。
• 订阅权益应按 expires_at_ms 更新，不要只保存“已购买”布尔值。
• 订阅可能续期、宽限期、过期、取消、换档，建议保留 raw 方便后续排查。
• 当前包提供订阅验单和优惠校验；如果业务要求服务端 acknowledge 订阅，需要使用 Google 订阅专用 acknowledge 接口，不能使用 acknowledgeGoogleProduct()。

Android Google Play 订阅优惠：

Google Play 订阅优惠和 Apple promotional offer 不一样。Apple 需要服务端生成签名；Google Play 订阅优惠不需要服务端签名，服务端也拿不到一个需要签名后返回给客户端的优惠参数。

Google Play 订阅优惠流程：

1. 客户端通过 Play Billing 查询 ProductDetails。
2. 客户端从 ProductDetails.SubscriptionOfferDetails 中选择一个优惠。
3. 客户端使用该优惠的 offerToken 发起购买。
4. 购买成功后，客户端把 Google 返回的 purchaseToken 发给服务端。
5. 服务端调用 verifyGoogleSubscriptionOffer() 验证该购买确实来自期望的 basePlanId / offerId。

服务端示例：

verifyGoogleSubscriptionOffer() 返回：

如果传入了 expectedBasePlanId 或 expectedOfferId，服务端会与 Google 返回的 offerDetails 对比；不一致会抛出异常，不应该给用户发放该优惠权益。

统一返回对象：

关键字段：

建议调用方业务处理：

LevelPlay 激励广告

在 LevelPlay 后台配置 S2S Rewarded Video Callback URL：

本包不提供默认 HTTP 控制器，也不注册默认路由。调用方需要在主项目中自行创建回调入口，调用本包完成验签，并保存 event_id 做唯一幂等。

业务控制器示例：

本地测试如果不方便生成 LevelPlay 签名，可以传入第二个参数 true 开启 dev 模式，跳过 LEVELPLAY_SECRET 和 signature 校验：

verifyRewardCallback() 返回：

Firebase Cloud Messaging 推送

由于 Android 和 iOS 不在同一个 Firebase 后台，本包在 config/mobile-push.php 中分别配置两套 service account：

发送到单个设备 token：

发送到 Android：

发送到 topic：

data 会统一转成字符串值，符合 FCM HTTP v1 对 data payload 的要求。FCM OAuth token 会按平台和 service account 缓存在 Redis 中。

数据库说明

本包没有迁移文件，也不会调用 DB、Model 或 Schema。推荐调用方自行维护这些业务表或存储：

• 用户第三方登录绑定表
• 充值订单表
• 内购交易幂等表
• 金币钱包表
• 金币流水表
• VIP 订阅表
• LevelPlay 广告事件表
• 短剧视频解锁表
• 设备推送 token 表