admel_sdk 1.1.2

AdMel SDK for Flutter - Audio advertisement plugin with banner display, VAST support, mute detection, and auto-refresh.

admel_sdk

AdMel SDK for Flutter — 音声広告プラグイン。バナー表示・VAST 対応・ミュート検出・オートリフレッシュ・スキップ可能広告・BGM ダッキング・コインリワード演出をサポートします。

機能

• VAST 準拠の音声広告再生 ＋ コンパニオンバナー表示
• 出現アニメーション（スライド / スケール）と画面比率での配置
• スキップ可能広告（広告グループ設定に応じてスキップボタンを自動表示）
• ミュート検出とミュート時の案内バナー
• オートリフレッシュ（デフォルト有効）
• 再生制御（pause / resume / stop）と音量制御
• BGM ダッキング（広告再生中にホストアプリの BGM を自動で下げる）
• コインリワード演出（再生完了時のコイン飛び出しアニメーション）

インストール

pubspec.yaml に追加します:

dependencies:
  admel_sdk: ^1.1.1

プラットフォーム要件

プラットフォーム	最小バージョン
iOS	12.0+
Android	API 21 (Android 5.0)+

使い方

初期化と表示

setMediaId() を呼んでから initialize()、その後 showAd() を呼びます。オートリフレッシュにより、以降の広告更新は自動で行われます。

import 'package:admel_sdk/admel_sdk.dart';

final admel = AdMelSdk();

// 1. メディアIDを設定（initialize の前）
await admel.setMediaId('your-media-id');

// 2. （任意）S2S コールバック用のユーザーID
await admel.setUserId('your-user-id');

// 3. 環境を指定して初期化
await admel.initialize(AdMelEnvironment.development); // or .production

// 4. 広告を表示
await admel.showAd('your-slot-id', position: 'top-right');

表示位置

position は top-left / top-right / bottom-left / bottom-right / center。offsetX / offsetY（px）で微調整できます。

画面比率で配置したい場合は relativeX / relativeY（0.0〜1.0、指定した座標が広告の中心）を使います。この場合 position / offset は無視されます。

// 画面中央やや上に、バネのスケール出現で表示
await admel.showAd(
  'your-slot-id',
  relativeX: 0.5,
  relativeY: 0.35,
  animation: 'scale', // 'slide'（デフォルト）| 'scale'
);

再生制御・状態取得

await admel.pause();
await admel.resume();
await admel.stopAudioAndHideBanner();

final playing = await admel.isPlaying();
final progress = await admel.getProgress();   // 0.0〜1.0
final position = await admel.getCurrentPosition(); // 秒
final duration = await admel.getDuration();        // 秒

await admel.setVolume(0.8);

ライフサイクルイベント

admel.setAdEventListeners(
  onAdStarted: () => print('広告開始'),
  onAdStopped: () => print('広告停止（完了・スキップ・停止・エラー）'),
  onAdCompleted: () => print('100%再生完了（スキップ時は発火しない）'),
  onMuteStateChanged: (isMuted) => print('ミュート: $isMuted'),
  // 広告のロード失敗（no-fill / ネットワーク / VAST エラー）。
  // showAd() は非同期のため常に成功で解決する点に注意。
  onAdFailedToLoad: (reason) => print('ロード失敗: $reason'),
);

オートリフレッシュ

await admel.setAutoRefresh(enabled: true, interval: 30);
final enabled = await admel.isAutoRefreshEnabled();

ミュート制御

final muted = await admel.isMuted();
// 広告を出さない画面ではミュート案内バナーを無効化
await admel.setMuteBannerEnabled(false);

BGM ダッキング（ゲーム等）

広告の音声再生中だけ、ホストアプリの BGM 音量を自動で下げます。コールバックを1回登録するだけで、開始/終了判定は SDK が管理します。

admel.enableBgmDucking(
  onDuck: () => myAudio.setBgmVolume(0.05),   // 広告中: BGMを下げる
  onRestore: () => myAudio.setBgmVolume(0.42), // 広告終了: BGMを戻す
);
// 解除
admel.disableBgmDucking();

スキップ可能広告

広告グループにスキップ設定がある広告が配信されると、SDK が自動的に、再生開始から指定秒後にバナー右上へ「✕」スキップボタンを表示します。スキップ可否はサーバー（広告グループ設定）で制御され、アプリ側の追加実装は不要です。

コインリワード演出（任意）

再生完了時にコインが飛び出す演出を表示できます。オーバーレイ表示のため MaterialApp の navigatorKey が必要です。

final navigatorKey = GlobalKey<NavigatorState>();

MaterialApp(navigatorKey: navigatorKey, /* ... */);

admel.enableCoinReward(
  navigatorKey: navigatorKey,
  config: const AdMelCoinRewardConfig(coinSize: 40.0),
);
// 解除
admel.disableCoinReward();

ドキュメント

• Flutter SDK クイックスタート / API リファレンス: AdMel Docs を参照してください。

ライセンス

MIT License. See LICENSE for details.