Godot TapTap Android Plugin

TapTap SDK + Dirichlet Ad SDK integration plugin for Godot 4.x Android.

Features

• TapTap Login - One-tap login with TapTap account
• Anti-addiction (Compliance) - Age verification and play time limits
• Cloud Save - Save/load game data to TapTap cloud
• Leaderboard - Submit and query leaderboard scores
• Friends - Get TapTap friends list
• Rewarded Video Ads - Dirichlet Ad SDK 4.2.5.0 integration
• Mock Mode - Automatic fallback for non-Android platforms (editor testing)

Requirements

• Godot 4.6+
• Android minSdk 24+
• TapTap Developer Account (Client ID, Client Token)
• Dirichlet Ad Developer Account (Media ID, Media Key, Space ID)

Quick Start

1. Install Plugin

Copy the addons/taptap_android/ folder into your Godot project's addons/ directory.

2. Enable Plugin

In Godot Editor: Project → Project Settings → Plugins → Enable "TapTap Android"

3. Add Autoloads

In Project → Project Settings → Autoload, add:

4. Configure AdApplication (Required for Ads)

1. Copy addons/taptap_android/android_build_template/AdApplication.java to your Android build template: android/build/src/main/java/com/godot/game/AdApplication.java

2. In your main script (before any ad calls), configure the AdApplication:

   # Call this early, before AdManager.init_ad()
   AdApplication.configure(media_id, media_key, "Your App Name", tap_client_id)
   

3. Modify android/build/src/main/AndroidManifest.xml:

   <application android:name=".AdApplication" ...>
   

5. Initialize SDK

func _ready():
    # Wait for TapTapManager to be ready
    TapTapManager.sdk_initialized.connect(_on_sdk_initialized)
    TapTapManager.login_success.connect(_on_login_success)
    TapTapManager.anti_addiction_callback.connect(_on_anti_addiction)

    # Initialize TapTap SDK
    TapTapManager.init_sdk("your_client_id", "your_client_token", "")

func _on_sdk_initialized():
    print("TapTap SDK initialized")

    # Initialize anti-addiction
    TapTapManager.init_anti_addiction("your_client_id")

    # Initialize cloud save
    TapTapManager.init_cloud_save()

    # Initialize leaderboard
    TapTapManager.init_leaderboard()

    # Initialize friends
    TapTapManager.init_friends()

    # Configure and initialize Ad SDK
    AdManager.configure("your_media_id", "your_media_key", "your_tap_client_id")
    AdManager.init_ad()

func _on_login_success(user_info: Dictionary):
    print("Logged in: ", user_info)
    # Check anti-addiction after login
    TapTapManager.check_anti_addiction()

func _on_anti_addiction(code: String, message: String):
    match code:
        "500":
            print("Login success / No restriction")
        "1030":
            print("Game time expired, should exit")
        _:
            print("Anti-addiction code=%s msg=%s" % [code, message])

6. Rewarded Video Ads

func show_rewarded_ad():
    if AdManager.is_loading():
        print("Ad is loading, please wait")
        return
    AdManager.rewarded_complete.connect(_on_ad_reward)
    AdManager.rewarded_close.connect(_on_ad_close)
    AdManager.rewarded_load_failed.connect(_on_ad_failed)
    AdManager.load_rewarded_video("your_space_id")

func _on_ad_reward(reward_info: String):
    print("Ad reward: ", reward_info)
    # Grant reward to player

func _on_ad_close():
    print("Ad closed")

func _on_ad_failed(reason: String):
    print("Ad failed: ", reason)

7. Cloud Save

func save_game():
    var save_data = JSON.stringify({"level": 5, "coins": 100})
    TapTapManager.save_to_cloud(save_data, "Level 5 - 100 coins")

func load_game():
    TapTapManager.cloud_save_list.connect(_on_save_list)
    TapTapManager.load_cloud_save_list()

func _on_save_list(archives_json: String):
    var json = JSON.new()
    if json.parse(archives_json) == OK:
        var archives = json.data.get("archives", [])
        if archives.size() > 0:
            TapTapManager.load_cloud_save_data(
                archives[0]["archiveId"],
                archives[0]["fileId"]
            )

API Reference

TapTapManager (Autoload)

AdManager (Autoload)

Important Notes

Ad SDK Initialization

Dirichlet Ad SDK MUST be initialized in Application.onCreate(). The AdApplication.java template handles this. Without it, you will get error code 100001 (ad material not found).

Privacy Controller

All privacy controller methods (isCanUseLocation, isCanUsePhoneState, etc.) return true by default. This is required for the SDK to obtain device information for ad targeting. Adjust if needed for your privacy policy.

Mock Mode

On non-Android platforms (editor, PC, etc.), both TapTapManager and AdManager automatically enter mock mode. Mock mode simulates successful responses with delays, allowing you to test your game logic without a real device.

Godot has_method() / has_signal() Pitfall

@UsedByGodot annotated methods and getPluginSignals() registered signals may return false for has_method()/has_signal(). Always call/connect them directly instead of checking first.

Signal Parameter Types

Godot emitSignal does not support Java primitive types (int, boolean, float). All signal parameters must use String type.

@UsedByGodot Default Parameters

Kotlin default parameters are NOT supported by Godot's JNI bridge. All parameters are treated as required.

Building the AAR from Source

If you need to modify the Kotlin plugin code:

1. Install Android Studio with Kotlin 2.1.0 support
2. Copy godot-lib.4.6.3.stable.template_release.aar to android_plugin_source/app/src/main/libs/
3. Run:

   cd android_plugin_source
   ./gradlew assembleRelease
   

4. Copy app/build/outputs/aar/app-release.aar to addons/taptap_android/android/taptap_plugin.aar

Directory Structure

godot-taptap-android/
├── addons/taptap_android/              # Godot plugin (copy to your project)
│   ├── plugin.cfg                      # Editor plugin config
│   ├── plugin.gd                       # Editor plugin script
│   ├── android/                        # Android plugin files
│   │   ├── TapTapPlugin.gdap           # TapTap plugin descriptor
│   │   ├── AdPlugin.gdap              # Ad plugin descriptor
│   │   ├── taptap_plugin.aar          # Compiled plugin AAR
│   │   └── dirichlet_ad_4.2.5.0.aar   # Dirichlet Ad SDK
│   ├── scripts/                        # GDScript autoloads
│   │   ├── tap_tap_manager.gd         # TapTap SDK wrapper
│   │   └── ad_manager.gd             # Ad SDK wrapper
│   └── android_build_template/        # Files to copy to android/build/
│       ├── AdApplication.java          # Ad SDK Application template
│       └── AndroidManifest.xml.patch   # Manifest modification guide
├── android_plugin_source/              # Kotlin source code for the AAR
│   ├── app/
│   │   ├── build.gradle
│   │   └── src/main/java/com/godot/taptap/
│   │       ├── taptap/TapTapPlugin.kt
│   │       └── ad/AdPlugin.kt
│   ├── build.gradle
│   ├── settings.gradle
│   └── gradle.properties
└── examples/                           # Example code

SDK Versions

License

MIT