本指南說明如何在 Flutter Web 應用程式中使用 YouTube Playables SDK。
Flutter 設定
預設的 Flutter 網路應用程式需要進行一些變更,才能做為可播放的內容。自 Flutter 3.24.5 版起,您必須進行下列變更。
根據預設,Flutter 會設定為從根目錄載入資源,而 Playables 則要求資源必須相對於進入點載入。這會顯示為 404 錯誤,或可能會顯示為 javascript 主控台中的錯誤,內容如下:Refused to execute script
from... because its MIME type ('text/html') is not executable.
如要重新設定這項設定,您可以從 index.html 檔案中移除下列標記:
<base href="$FLUTTER_BASE_HREF">
根據預設,Flutter 會動態載入部分程式庫,而不是將程式庫嵌入應用程式。CanvasKit 就是這類程式庫的例子。這會在 JavaScript 控制台中顯示為錯誤,內容如下:Refused to connect to '...' because it
violates the following Content Security Policy directive: "connect-src 'self'
blob: data:".
在載入失敗時,Flutter 也可能會輸出其他記錄,例如 Failed to download any of the following CanvasKit URLs
。如要修正這個問題,您可以使用下列額外標記建構網頁應用程式:
$ flutter build web --no-web-resources-cdn
根據預設,Flutter 網頁應用程式會動態載入字型,而不是將字型嵌入應用程式。預設的 Flutter 應用程式會使用 Roboto 字型,這會在 JavaScript 主控台中顯示為錯誤,內容如下:Refused to connect to '...'
because it violates the following Content Security Policy directive:
"connect-src 'self' blob: data".
如要修正這個問題,您可以採取下列步驟:
- 在 Flutter 網頁應用程式的根目錄中建立名為「fonts」的資料夾
- 前往 fonts.google.com 下載 Roboto 字型系列。
- 解壓縮字型,並將 Roboto-Regular.ttf 複製到字型資料夾
- 在您的 flutter 網頁應用程式的 pubspec.yaml 中加入以下行:
fonts:
- family: Roboto
fonts:
- asset: fonts/Roboto-Regular.ttf
如要進一步瞭解字型設定,請參閱 Flutter 說明文件。
SDK 整合
您可以透過類似以下的 JS 互通包裝函式,從 Flutter Web 遊戲使用 YouTube Playables SDK:
ytgame.dart
// Copyright 2023 The Flutter Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
@JS()
library ytgame_api;
import 'package:js/js.dart';
import 'package:js/js_util.dart' as js_util;
enum PlayablesErrorType {
unknown('UNKNOWN'),
apiUnavailable('API_UNAVAILABLE'),
invalidParams('INVALID_PARAMS'),
sizeLimitExceeded('SIZE_LIMIT_EXCEEDED');
const PlayablesErrorType(String type) : _type = type;
final String _type;
@override
String toString() => _type;
static PlayablesErrorType fromString(String errorType) {
return values.firstWhere(
(element) => element._type == errorType,
);
}
}
@JS()
@staticInterop
class PlayablesError {}
extension PlayablesErrorExtension on PlayablesError {
@JS('errorType')
external String get _errorType;
PlayablesErrorType get errorType {
return PlayablesErrorType.fromString(_errorType);
}
}
@JS()
@anonymous
@staticInterop
class PlayablesScore {
external factory PlayablesScore({
required num value,
});
}
extension PlayablesScoreExtension on PlayablesScore {
external num get value;
}
// engagement
@JS()
@staticInterop
class PlayablesEngagement {}
extension PlayablesEngagementExtension on PlayablesEngagement {
@JS('sendScore')
external Object _sendScore(PlayablesScore score);
Future<void> sendScore(PlayablesScore score) {
return js_util.promiseToFuture(_sendScore(score));
}
}
// game
@JS()
@staticInterop
class PlayablesGame {}
extension PlayablesGameExtension on PlayablesGame {
external void firstFrameReady();
external void gameReady();
@JS('loadData')
external Object _loadData();
Future<String?> loadData() {
return js_util.promiseToFuture<String?>(_loadData());
}
@JS('saveData')
external Object _saveData(String? data);
Future<void> saveData(String? data) {
return js_util.promiseToFuture<void>(_saveData(data));
}
}
// health
@JS()
@staticInterop
class PlayablesHealth {}
extension PlayablesHealthExtension on PlayablesHealth {
external void logError();
external void logWarning();
}
// system
typedef PlayablesUnsetCallback = void Function();
typedef PlayablesOnAudioEnabledChange = void Function(bool isAudioEnabled);
typedef PlayablesOnPause = void Function();
typedef PlayablesOnResume = void Function();
@JS()
@staticInterop
class PlayablesSystem {}
extension PlayablesSystemExtension on PlayablesSystem {
external bool isAudioEnabled();
@JS('onAudioEnabledChange')
external PlayablesUnsetCallback _onAudioEnabledChange(
PlayablesOnAudioEnabledChange callback);
PlayablesUnsetCallback onAudioEnabledChange(
PlayablesOnAudioEnabledChange callback) {
return _onAudioEnabledChange(allowInterop(callback));
}
@JS('onPause')
external PlayablesUnsetCallback _onPause(PlayablesOnPause callback);
PlayablesUnsetCallback onPause(PlayablesOnPause callback) {
return _onPause(allowInterop(callback));
}
@JS('onResume')
external PlayablesUnsetCallback _onResume(PlayablesOnResume callback);
PlayablesUnsetCallback onResume(PlayablesOnResume callback) {
return _onResume(allowInterop(callback));
}
}
@JS()
@staticInterop
class Playables {}
extension PlayablesExtension on Playables {
@JS('SDK_VERSION')
external String get sdkVersion;
external PlayablesEngagement get engagement;
external PlayablesGame get game;
external PlayablesHealth get health;
external PlayablesSystem get system;
}
@JS('ytgame')
external Playables get ytgame;
用量
- 請按照這篇文章的操作說明設定及初始化 Web SDK。
- 修改 Flutter Web 應用程式的
web/index.html
,納入必要的指令碼標記。
- 修改 Flutter Web 應用程式的
- 在 Flutter 網路應用程式的
src
中新增ytgame.dart
的副本。 - 請確認已將 js 套件新增至 Flutter,例如執行
flutter pub add js
指令。 - 視需要新增
import 'src/location/of/ytgame.dart';
。 - 使用
ytgame
物件存取 SDK。
範例
以下列舉幾個 Dart API 的實際運作範例。
firstFrameReady
和gameReady
為了讓遊戲正確啟動,您需要在第一個影格準備好顯示時呼叫 firstFrameReady
,並在遊戲準備好進行互動時呼叫 gameReady
。在預設的 Flutter 應用程式中執行此操作的方法之一,是將呼叫新增至 main.dart 檔案:
...
import 'src/ytgame.dart';
...
void main() {
ytgame.game.firstFrameReady();
ytgame.game.gameReady();
runApp(const MyApp());
}
請注意,這只是讓遊戲運作的範例,您需要正確放置這些呼叫的位置,才能提供正確的實作方式。
sendScore
以下範例說明如何在 Dart 中實作 sendScore(int points)
:
...
import 'src/ytgame.dart';
...
/// Sends [points] as score to YT Playables
Future<void> sendScore(int points) async {
// Create a score object...
final PlayablesScore score = PlayablesScore(
value: points,
);
// Submit the score to ytgame
await ytgame.engagement.sendScore(score);
}
onPause
以下範例說明遊戲如何監聽來自 YT Playables 的 Pause
事件,以便在需要時暫停引擎:
...
import 'src/ytgame.dart';
...
/// The instance of your game.
late Game myGame;
/// Callback to stop listening for Pause events (cleanup).
PlayablesUnsetCallback? _unsetOnPause;
...
/// Sets a [callback] to respond to Pause events.
void registerOnPauseListener(PlayablesOnPause callback) {
_unsetOnPause = ytgame.system.onPause(callback);
}
/// Stops listening to Pause events, and clears [_unsetOnPause].
void unsetOnPauseListener() {
if (_unsetOnPause != null) {
_unsetOnPause!();
_unsetOnPause = null;
}
}
...
/// Initialization for your game
void initGame() {
...
myGame = ...
registerOnPauseListener(_onPause);
}
void _onPause() {
// This is called when a Pause event is received from YT Playables.
myGame.pauseEngine();
}
/// Teardown for your game
void disposeGame() {
...
unsetOnPauseListener();
}
請參閱完整的 YT Playables API 參考資料。