318 lines
8.4 KiB
Markdown
318 lines
8.4 KiB
Markdown
# 第三方 SDK 集成配置指南
|
||
|
||
本文档说明换皮应用如何配置 Adjust、Facebook App Events 和 Google Play 内购三大 SDK。
|
||
|
||
---
|
||
|
||
## 配置文件
|
||
|
||
请填写以下配置文件（放在项目根目录或 `docs/` 目录下）：
|
||
|
||
```json
|
||
{
|
||
"adjust": {
|
||
"app_token": "your_adjust_app_token",
|
||
"environment": "sandbox",
|
||
"event_tokens": {
|
||
"tier_599": "event_token_599",
|
||
"tier_999": "event_token_999",
|
||
"tier_1999": "event_token_1999",
|
||
"tier_4999": "event_token_4999",
|
||
"tier_9999": "event_token_9999",
|
||
"first_purchase": "event_token_first",
|
||
"purchase": "event_token_purchase",
|
||
"register": "event_token_register"
|
||
}
|
||
},
|
||
"facebook": {
|
||
"app_id": "your_facebook_app_id",
|
||
"client_token": "your_facebook_client_token"
|
||
},
|
||
"google_play": {
|
||
"product_ids": {
|
||
"tier_599": "com.example.product.599",
|
||
"tier_999": "com.example.product.999",
|
||
"tier_1999": "com.example.product.1999",
|
||
"tier_4999": "com.example.product.4999",
|
||
"tier_9999": "com.example.product.9999"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 一、Adjust SDK 配置
|
||
|
||
### 1.1 所需信息
|
||
|
||
| 字段 | 说明 | 获取位置 |
|
||
|------|------|----------|
|
||
| `app_token` | Adjust App Token | Adjust Dashboard → App Settings |
|
||
| `environment` | `sandbox`（测试）或 `production`（正式） | 根据构建环境选择 |
|
||
|
||
### 1.2 Android 配置
|
||
|
||
> **重要**：Facebook SDK 必须在 Flutter 引擎启动前初始化。以下步骤确保初始化顺序正确：
|
||
> 1. `Application.onCreate()` → 初始化 Facebook SDK
|
||
> 2. `MainActivity.configureFlutterEngine()` → 缓存 FlutterEngine
|
||
> 3. `Application` 通过 `FlutterEngineCache` 通知 Dart 层
|
||
|
||
**1. AndroidManifest.xml** - 添加权限和 Adjust App Token：
|
||
```xml
|
||
<manifest>
|
||
<uses-permission android:name="android.permission.INTERNET"/>
|
||
|
||
<application>
|
||
<!-- Adjust 配置 -->
|
||
<meta-data
|
||
android:name="com.adjust.sdk.appToken"
|
||
android:value="your_adjust_app_token" />
|
||
<meta-data
|
||
android:name="com.adjust.sdk.environment"
|
||
android:value="sandbox" />
|
||
|
||
<!-- Facebook SDK 配置 -->
|
||
<meta-data
|
||
android:name="com.facebook.sdk.ApplicationId"
|
||
android:value="@string/facebook_app_id" />
|
||
<meta-data
|
||
android:name="com.facebook.sdk.ClientToken"
|
||
android:value="@string/facebook_client_token" />
|
||
</application>
|
||
</manifest>
|
||
```
|
||
|
||
**2. res/values/strings.xml** - 添加 Facebook 配置：
|
||
```xml
|
||
<resources>
|
||
<string name="facebook_app_id">your_facebook_app_id</string>
|
||
<string name="facebook_client_token">your_facebook_client_token</string>
|
||
</resources>
|
||
```
|
||
|
||
**3. app/build.gradle** - 添加 Facebook 依赖：
|
||
```groovy
|
||
dependencies {
|
||
implementation 'com.facebook.android:facebook-core:18.0.0'
|
||
}
|
||
```
|
||
|
||
**4. 创建 Application 类** - Facebook SDK 初始化（**必须**）：
|
||
|
||
创建 `android/app/src/main/kotlin/<package>/App.kt`：
|
||
```kotlin
|
||
package com.your.package.name
|
||
|
||
import android.app.Application
|
||
import android.os.Handler
|
||
import android.os.Looper
|
||
import com.facebook.FacebookSdk
|
||
import com.facebook.LoggingBehavior
|
||
import com.facebook.appevents.AppEventsLogger
|
||
import io.flutter.embedding.engine.FlutterEngineCache
|
||
import io.flutter.plugin.common.MethodChannel
|
||
|
||
class App : Application() {
|
||
companion object {
|
||
const val CHANNEL = "com.your.package.name/facebook_sdk"
|
||
const val ENGINE_ID = "main"
|
||
}
|
||
|
||
override fun onCreate() {
|
||
super.onCreate()
|
||
|
||
FacebookSdk.sdkInitialize(this)
|
||
FacebookSdk.setIsDebugEnabled(true)
|
||
FacebookSdk.addLoggingBehavior(LoggingBehavior.APP_EVENTS)
|
||
|
||
// 通知 Dart 层 Facebook SDK 已初始化
|
||
Handler(Looper.getMainLooper()).postDelayed({
|
||
val engine = FlutterEngineCache.getInstance().get(ENGINE_ID)
|
||
if (engine != null) {
|
||
MethodChannel(engine.dartExecutor.binaryMessenger, CHANNEL)
|
||
.invokeMethod("onFacebookSdkInitialized", null)
|
||
}
|
||
}, 100)
|
||
}
|
||
}
|
||
```
|
||
|
||
**5. 更新 MainActivity.kt** - 处理 SDK 初始化回调：
|
||
```kotlin
|
||
package com.your.package.name
|
||
|
||
import android.os.Handler
|
||
import android.os.Looper
|
||
import com.facebook.appevents.AppEventsLogger
|
||
import io.flutter.embedding.android.FlutterActivity
|
||
import io.flutter.embedding.engine.FlutterEngine
|
||
import io.flutter.embedding.engine.FlutterEngineCache
|
||
import io.flutter.plugin.common.MethodChannel
|
||
|
||
class MainActivity : FlutterActivity() {
|
||
companion object {
|
||
const val CHANNEL = "com.your.package.name/facebook_sdk"
|
||
const val ENGINE_ID = "main"
|
||
}
|
||
|
||
override fun configureFlutterEngine(flutterEngine: FlutterEngine) {
|
||
super.configureFlutterEngine(flutterEngine)
|
||
|
||
AppEventsLogger.activateApp(application)
|
||
|
||
MethodChannel(flutterEngine.dartExecutor.binaryMessenger, CHANNEL)
|
||
.setMethodCallHandler { call, _ ->
|
||
if (call.method == "waitForFacebookSdkInit") {
|
||
AppEventsLogger.activateApp(application)
|
||
}
|
||
}
|
||
|
||
// 缓存 FlutterEngine 供 Application 类使用
|
||
Handler(Looper.getMainLooper()).postDelayed({
|
||
FlutterEngineCache.getInstance().put(ENGINE_ID, flutterEngine)
|
||
}, 100)
|
||
}
|
||
}
|
||
```
|
||
|
||
**6. 更新 AndroidManifest.xml** - 使用 Application 类：
|
||
```xml
|
||
<application
|
||
android:name=".App"
|
||
android:label="Your App Name"
|
||
...>
|
||
```
|
||
|
||
**注意**：Facebook SDK 必须在 Flutter 引擎启动前初始化，使用 Application 类 + MethodChannel 确保时序正确。
|
||
|
||
### 1.3 iOS 配置
|
||
|
||
**1. Info.plist** - 添加配置：
|
||
```xml
|
||
<key>AdjustAppToken</key>
|
||
<string>your_adjust_app_token</string>
|
||
<key>AdjustEnvironment</key>
|
||
<string>sandbox</string>
|
||
|
||
<key>FacebookAppID</key>
|
||
<string>your_facebook_app_id</string>
|
||
<key>FacebookClientToken</key>
|
||
<string>your_facebook_client_token</string>
|
||
<key>FacebookDisplayName</key>
|
||
<string>Your App Name</string>
|
||
```
|
||
|
||
---
|
||
|
||
## 二、Facebook App Events 配置
|
||
|
||
### 2.1 所需信息
|
||
|
||
| 字段 | 说明 | 获取位置 |
|
||
|------|------|----------|
|
||
| `app_id` | Facebook 应用 ID | Facebook Developer Console → Your App → Settings → Basic |
|
||
| `client_token` | 客户端口令 | Facebook Developer Console → Your App → Settings → Advanced |
|
||
|
||
### 2.2 配置步骤
|
||
|
||
按 **1.1** 和 **1.2** 中的 Android/iOS 配置说明添加 `facebook_app_id` 和 `facebook_client_token`。
|
||
|
||
---
|
||
|
||
## 三、Google Play 内购配置
|
||
|
||
### 3.1 所需信息
|
||
|
||
| 字段 | 说明 | 获取位置 |
|
||
|------|------|----------|
|
||
| `product_ids` | Google Play Console 商品 ID | Google Play Console → Monetize → Products → Subscriptions/In-app products |
|
||
|
||
### 3.2 Android 配置
|
||
|
||
**1. AndroidManifest.xml** - 添加权限：
|
||
```xml
|
||
<uses-permission android:name="com.android.vending.BILLING"/>
|
||
```
|
||
|
||
**2. app/build.gradle** - 添加依赖：
|
||
```groovy
|
||
dependencies {
|
||
implementation 'com.android.billingclient:billing-ktx:6.0.0'
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 四、框架初始化代码
|
||
|
||
在 `main.dart` 中初始化：
|
||
|
||
```dart
|
||
import 'package:client_proxy_framework/client_proxy_framework.dart';
|
||
|
||
void main() async {
|
||
WidgetsFlutterBinding.ensureInitialized();
|
||
|
||
// 1. 初始化 API 客户端
|
||
ApiClient.init(YourAppConfig());
|
||
|
||
// 2. 初始化分析服务
|
||
AnalyticsService.init(
|
||
AnalyticsConfig(
|
||
adjustConfig: AdjustConfig(
|
||
appToken: 'your_adjust_app_token',
|
||
environment: AdjustEnv.sandbox, // 上线改为 AdjustEnv.production
|
||
logLevel: AdjustLogLevel.verbose,
|
||
),
|
||
facebookConfig: FacebookConfig(
|
||
appId: 'your_facebook_app_id',
|
||
debugLogs: true,
|
||
),
|
||
debugLogs: true,
|
||
),
|
||
);
|
||
|
||
// 3. 启动应用
|
||
runApp(const YourApp());
|
||
|
||
// 4. 初始化认证服务
|
||
await AuthService.init();
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 五、事件埋点示例
|
||
|
||
```dart
|
||
// Adjust 事件埋点
|
||
AnalyticsService.trackEvent('your_event_token');
|
||
|
||
// Facebook 购买事件
|
||
AnalyticsService.trackPurchase(amount: 9.99, currency: 'USD');
|
||
|
||
// Facebook 注册事件
|
||
AnalyticsService.trackRegister();
|
||
|
||
// Facebook 订阅事件
|
||
AnalyticsService.trackSubscribe('monthly_vip');
|
||
```
|
||
|
||
---
|
||
|
||
## 六、获取 SDK 配置信息的位置
|
||
|
||
### Adjust
|
||
- Dashboard: https://dashboard.adjust.com
|
||
- App Settings → App Tokens
|
||
|
||
### Facebook
|
||
- Developer Console: https://developers.facebook.com
|
||
- Settings → Basic (App ID)
|
||
- Settings → Advanced → Client Token
|
||
|
||
### Google Play
|
||
- Play Console: https://play.google.com/console
|
||
- Monetize → Products → Subscriptions/In-app products
|