Flutter游戏互动插件gameball_sdk的使用

Gameball Flutter SDK 是一个库，允许你将 Gameball 平台的功能集成到你的 Flutter 应用程序中。它使你能够：

• 注册客户并跟踪他们的活动。
• 发送个性化事件以触发 Gameball 活动。
• 在你的应用内展示 Gameball 用户界面。

安装

1. 将 Gameball Flutter SDK 依赖项添加到你的 pubspec.yaml 文件或直接使用 flutter pub add 命令：

dependencies:
  gameball_sdk: ^latest

$ flutter pub add gameball_sdk

1. 在你的 Dart 代码中导入该库：

import 'package:gameball_sdk/gameball_sdk.dart';

使用

初始化

1. 创建 GameballApp 的实例：

GameballApp gameballApp = GameballApp.getInstance();

1. 使用你的 API 密钥、语言、平台和商店信息初始化 Gameball SDK：

gameballApp.init("{api_key}", "{lang}", "{platform}", "{shop}");

Firebase 初始化（用于推荐处理）

确保在使用推荐功能之前已初始化 Firebase：

import 'package:firebase_core/firebase_core.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp();
  // ... 其余的应用程序代码
}

客户注册

注册一个具有唯一标识符、电子邮件（可选）、手机号码（可选）及自定义属性的客户：

CustomerAttributes customerAttributes = CustomerAttributes(
  displayName: "John Doe",
  firstName: "John",
  lastName: "Doe",
  mobileNumber: "0123456789",
  preferredLanguage: "en",
  customAttributes: {
    "{key}": "{value}",
  },
);

gameballApp.registerCustomer(
  "{customerId}",
  "{customerEmail}",
  "{customerMobile}",
  false, // isGuest = false
  customerAttributes,
  (response, error) {
    // 处理注册响应
  },
);

发送事件

定义一个包含客户唯一标识符和事件详情的 Event 对象：

Event eventBody = Event(
  customerId: "{customerId}",
  events: {
    "{eventName}": {
      "{prop1}": "{value1}",
    },
  },
);

gameballApp.sendEvent(eventBody, (success, error) {
  // 处理发送事件的响应
});

显示 Gameball 个人资料

在你的应用程序中展示 Gameball 用户界面：

gameballApp.showProfile(context, "{customerId}", "{openDetail}", "{hideNavigation}", "{showCloseButton}");

• 替换 context 为当前构建上下文。
• 使用占位符替换 {customerId}、{openDetail}（可选的 URL，在个人资料内打开）、{hideNavigation}（可选的布尔值，隐藏/显示导航箭头）、{showCloseButton}（可选的布尔值，隐藏/显示关闭按钮）。
• 注意：将所有 {...} 占位符替换为实际值。

示例代码

以下是完整的示例代码：

import 'package:firebase_core/firebase_core.dart';
import 'package:flutter/material.dart';
import 'package:gameball_sdk/gameball_sdk.dart';
import 'package:gameball_sdk/models/requests/event.dart';
import 'package:gameball_sdk/models/requests/customer_attributes.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  [@override](/user/override)
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      theme: ThemeData(
        colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple),
        useMaterial3: true,
      ),
      home: const MyHomePage(title: 'Flutter Demo Home Page'),
    );
  }
}

class MyHomePage extends StatefulWidget {
  const MyHomePage({super.key, required this.title});

  final String title;

  [@override](/user/override)
  State<MyHomePage> createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  GameballApp gameballApp = GameballApp.getInstance();

  void _testGameball() {
    Firebase.initializeApp().then((response) {});

    // TODO 替换大括号之间的值为实际值

    gameballApp.init("{api_key}", "{lang}", "{platform}", "{shop}");

    setState(() {
      customerRegistrationCallback(response, error) {
        if (error == null && response != null) {
          gameballApp.showProfile(context, "{customerId}", "{openDetail}", false);
        } else {
          // TODO
        }
      }

      CustomerAttributes customerAttributes = CustomerAttributes(
          displayName: "John Doe",
          firstName: "John",
          lastName: "Doe",
          mobileNumber: "0123456789",
          preferredLanguage: "en",
          customAttributes: {
            "{key}": "{value}"
          }
      );

      gameballApp.registerCustomer(
          "{customerId}",
          "{customerEmail}",
          "{customerMobile}",
          false, // isGuest = false, 不是访客
          customerAttributes,
          customerRegistrationCallback);

      sendEventCallback(response, error) {
        if (error == null && response != null) {
          // TODO
        } else {
          // TODO
        }
      }

      Event eventBody = Event(
          customerId: "{customerId}",
          events: {
            "{eventName}": {
              "{prop1}": "{value1}"
            }
          });

      gameballApp.sendEvent(eventBody, sendEventCallback);
    });
  }

  [@override](/user/override)
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        backgroundColor: Theme.of(context).colorScheme.inversePrimary,
        title: Text(widget.title),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            Text(
              'Gameball Demo',
              style: Theme.of(context).textTheme.headlineLarge,
            ),
            Text(
              '点击下方的 FAB',
              style: Theme.of(context).textTheme.headlineMedium,
            ),
          ],
        ),
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: _testGameball,
        tooltip: '尝试 Gameball',
        child: const Icon(Icons.play_arrow),
      ),
    );
  }
}