Godot Deeplink Plugin

Deeplink plugin provides a unified GDScript interface for processing of App Links on the Android platform and Universal Links on the iOS platform in order to enable direct navigation to specific app content.

Features:

• Enable web links to directly access app content.
• Provide support for custom schemes.
• Check if a domain is associated with app.
• Forward users to related app settings on platform.

Table of Contents

• Demo
• Installation
• Usage
• Signals
• Methods
• Classes
• Export
• Platform-Specific Notes
• Links
• All Plugins
• Credits
• Contributing

Demo

Try the demo app located in the demo directory.

Installation

Uninstall previous versions before installing. If using both Android & iOS, ensure same addon interface version.

Options:

1. AssetLib
   • Search for Deeplink
   • Click Download --> Install
   • Install to project root, Ignore asset root checked
   • Enable via Project --> Project Settings --> Plugins
   • Ignore file conflict warnings when installing both versions
2. Manual
   • Download release from GitHub
   • Unzip to project root
   • Enable via Plugins tab

Usage

• Add Deeplink nodes to your scene per URL association and follow the following steps:
  • set the required field on each Deeplink node
    • scheme - schemes like http, https, or a custom scheme (don't include ://)
    • host - domain name
    • path prefix - optional path before link is considered a deeplink
  • note that scheme, host, and path prefix must all match for a URI to be processed by the app
    • leave path prefix empty to process all paths in host
• register a listener for the deeplink_received signal
  • process url, scheme, host, and path data from the signal
• invoke the initialize() method at startup
  • initialize() plugin and connect its signals as early as possible (ie. in _ready() lifecycle method of your main node)
• alternatively, use the following methods to get most recent deeplink data:
  • get_link_url() -> full URL for the deeplink
  • get_link_scheme() -> scheme for the deeplink (ie. 'https')
  • get_link_host() -> host for the deeplink (ie. 'www.example.com')
  • get_link_path() -> path for the deeplink (the part that comes after host)
• additional methods:
  • is_domain_associated(a_domain: String) -> returns true if your application is correctly associated with the given domain on the tested device
    • _note: is_domain_associated() method does not support custom schemes_
  • navigate_to_open_by_default_settings() -> navigates to the Android OS' Open by Default settings screen for your application

Usage Example:

extends Node

@onready var deeplink: Deeplink = $Deeplink


func _ready() -> void:
    # Initialize the plugin as early as possible
    deeplink.initialize()

    # Connect the signal (can also be done in the editor)
    deeplink.deeplink_received.connect(_on_deeplink_received)


func _on_deeplink_received(url: DeeplinkUrl) -> void:
    print("Full URL: ", url.get_url())
    print("Scheme: ", url.get_scheme())
    print("Host: ", url.get_host())
    print("Path: ", url.get_path())
    print("Query: ", url.get_query())

Notes:

• initialize() should be called in the main scene’s _ready() method.
• The deeplink_received signal is emitted only when the URL matches the configured scheme, host, and optional path_prefix.
• Deeplink data is also accessible via get_link_*() methods on the Deeplink node.

Signals

• deeplink_received(url: DeeplinkUrl): Emitted when app content is requested via deeplink. Must be connected at startup, as early as possible, or via Godot Editor.

Methods

• initialize() -> int Initializes the native plugin and connects platform-specific listeners. Must be called as early as possible, ideally in _ready() of the main scene.
• navigate_to_open_by_default_settings() -> void Opens the Android Open by Default settings screen for the application. Android only.
• get_link_url() -> String Returns the full deeplink URL as a string.
• get_link_scheme() -> String Returns the scheme of the last received deeplink (e.g. https, myapp).
• get_link_host() -> String Returns the host/domain of the last received deeplink.
• get_link_path() -> String Returns the path portion of the last received deeplink.
• clear_data() -> void Clears stored deeplink data inside the plugin.

Android-only Methods

• is_domain_associated(a_domain: String) -> bool Returns true if the given domain is correctly associated with the app on the current device. Android only. Custom schemes are not supported.

Classes

Plugin classes.

Deeplink

Main node used to declare and configure deeplink associations for your application.

Responsibilities:

• Defines which scheme, host, and optional path_prefix should be handled
• Exports deeplink configuration for Android App Links and iOS Universal Links
• Connects to the native plugin singleton
• Emits the deeplink_received signal when a matching deeplink is opened

Typical usage:

• Add one or more Deeplink nodes to your scene
• Configure their exported properties
• Call initialize() at startup
• Listen to deeplink_received signal

DeeplinkUrl

Lightweight wrapper class representing a parsed deeplink URL.

This class is constructed from native platform data and provides structured access to URL components such as:

• scheme
• user
• password
• host
• port
• path
• path_components
• query
• fragment

It is emitted as the argument of the deeplink_received signal and can also reconstruct the full URL string.

Sample usage:

func _on_deeplink_received(url: DeeplinkUrl) -> void:
    print(url.get_url())
    print(url.get_host())
    print(url.get_path())

Export

Three options:

• Add Deeplink node to main scene
• Open scene with Deeplink nodes in the editor before export
• Use file-based export

1. File-based Export Configuration In order to enable file-based export configuration, an export.cfg file should be placed in the addons/DeeplinkPlugin directory. The export.cfg configuration file may contain multiple deeplink configurations. The scheme and host properties are mandatory for each deeplink configuration.

The following is a sample export.cfg file:

[Deeplink1]
scheme = "https"
host = "www.example.com"

[Deeplink2]
scheme = "https"
host = "www.example2.com"

Example export.cfg file with Android-specific properties:

[Deeplink3]
label = "deeplink1"
is_auto_verify = true
is_default = true
is_browsable = true
scheme = "https"
host = "www.example.com"
path_prefix = "/my_data"

1. Node-based Export Configuration If export.cfg file is not found or file-based configuration is invalid, then the plugin will attempt to load node-based configuration.

During iOS export, the plugin searches for Deeplink nodes in the scene that is open in the Godot Editor. If none found, then the plugin searches for Deeplink nodes in the project's main scene. Therefore;

• Make sure that the scene that contains the Deeplink node(s) is selected in the Godot Editor when building and exporting for Android, or
• Make sure that your Godot project's main scene contains one or more Deeplink nodes.

Platform-Specific Notes

In addition to adding and enabling the plugin, platform-level configuration is also required before deeplinks can work.

Android

• Build: Create custom Android gradle build.
• Domain Association: Associate Godot app with a domain.
• Custom schemes: Chrome has issues opening custom schemes; Firefox is able to open them successfully.
• Testing:
  1. Use adb shell as follows:
     • $> adb shell am start -a android.intent.action.VIEW -c android.intent.category.BROWSABLE -d "https://www.example.com/mydata/path"
• Troubleshooting:
  • Logs: adb logcat | grep 'godot' (Linux), adb.exe logcat | select-string "godot" (Windows)

iOS

• Domain Association: Associate Godot app with a domain.
• Troubleshooting:
  • View XCode logs while running the game for troubleshooting.
  • See Godot iOS Export Troubleshooting.

Links

• AssetLib Entry Android
• AssetLib Entry iOS

All Plugins

Credits

Developed by Cengiz

Based on Godot Mobile Plugin Template

Original repository: Godot Deeplink Plugin

Contributing

See the contribution guide if you would like to contribute to this project.