Playgama Bridge SDK Integration for Defold

Playgama Bridge is a cross-platform SDK for publishing Defold HTML5 games across 20+ platforms including Playgama, YouTube, Yandex Games, Crazy Games, Poki, Facebook, Telegram, Xiaomi, and more.

Installation

1. Copy the Source code.zip link from the GitHub releases page
2. Add it as a dependency in your project settings (game.project file)
3. Select Project -> Fetch Libraries to download the SDK

Configuration

1. Download the playgama-bridge-config.json file from the GitHub releases
2. Place it in the res/web folder
3. Ensure the /res directory is added to Bundle Resources in project settings
4. Configure game identifiers and in-app purchases in the config file

HTML5 Export

When building for HTML5, select the appropriate index template provided by the SDK to ensure proper initialization.

Initialization

Once the game is loaded, the plugin is already initialized. No additional actions are required. Access all modules through the bridge module:

local bridge = require("bridge.bridge")

bridge.platform
bridge.player
bridge.device
bridge.storage
bridge.advertisement
bridge.payments
bridge.leaderboards
bridge.social
bridge.achievements

After game is fully loaded, send the game ready message:

bridge.platform.send_message("game_ready")

Device

local bridge = require("bridge.bridge")

-- Device type: 'mobile', 'tablet', 'desktop', 'tv'
local device_type = bridge.device.type()

Platform

local bridge = require("bridge.bridge")

-- Platform ID: 'playgama', 'vk', 'yandex', 'crazy_games', etc.
local platform_id = bridge.platform.id()

-- User language (ISO 639-1): 'en', 'ru', etc.
local language = bridge.platform.language()

-- Top-level domain: 'com', 'ru', or nil
local tld = bridge.platform.tld()

-- URL payload (auxiliary information from game URL)
local payload = bridge.platform.payload()

Server Time

local bridge = require("bridge.bridge")

function init(self)
    bridge.platform.get_server_time(function (_, data)
        print("Server time: ", data)
    end, function ()
        -- error
    end)
end

Platform Messages

bridge.platform.send_message("game_ready")
bridge.platform.send_message("gameplay_started")
bridge.platform.send_message("gameplay_stopped")
bridge.platform.send_message("in_game_loading_started")
bridge.platform.send_message("in_game_loading_stopped")
bridge.platform.send_message("player_got_achievement")

Audio State Listener

local bridge = require("bridge.bridge")

function init(self)
    bridge.platform.on("audio_state_changed", function (_, is_enabled)
        print("Is audio enabled: ", is_enabled)
        -- Mute/unmute game audio based on is_enabled
    end)
end

Pause State Listener

local bridge = require("bridge.bridge")

function init(self)
    bridge.platform.on("pause_state_changed", function (_, is_paused)
        print("Is paused: ", is_paused)
        -- Pause/resume game based on is_paused
    end)
end

Player

local bridge = require("bridge.bridge")

-- Check authorization support
local is_auth_supported = bridge.player.is_authorization_supported()

-- Check if player is authorized
local is_authorized = bridge.player.is_authorized()

-- Player ID (nil if not authorized)
local player_id = bridge.player.id()

-- Player name (nil if unavailable)
local player_name = bridge.player.name()

-- Player photos (array of URLs sorted by resolution, or empty array)
local photos = bridge.player.photos()

-- Platform-specific player data
local extra = bridge.player.extra()

Authorization

local bridge = require("bridge.bridge")

function init(self)
    local options = {}

    bridge.player.authorize(
        options,
        function ()
            -- success
            print("Authorized: ", bridge.player.id())
        end,
        function ()
            -- error
            print("Authorization failed")
        end)
end

Storage

Get Data

local bridge = require("bridge.bridge")

function init(self)
    bridge.storage.get(
        { "coins", "level" },
        function (_, data)
            if data.coins then
                print("Coins: ", data.coins)
            end
            if data.level then
                print("Level: ", data.level)
            end
        end,
        function ()
            -- error
        end
    )
end

Set Data

local bridge = require("bridge.bridge")

function init(self)
    bridge.storage.set(
        { coins = 42, level = "dungeon" },
        function (_)
            -- success
            print("Data saved")
        end,
        function (_)
            -- error
        end
    )
end

Delete Data

local bridge = require("bridge.bridge")

function init(self)
    bridge.storage.delete(
        { "coins", "level" },
        function ()
            -- success
        end,
        function ()
            -- error
        end
    )
end

Banner Ads

local bridge = require("bridge.bridge")

-- Check support
local is_supported = bridge.advertisement.is_banner_supported()

-- Show banner
function init(self)
    local position = "bottom"  -- 'top' or 'bottom', default = 'bottom'
    local placement = "menu"   -- optional
    bridge.advertisement.show_banner(position, placement)
end

-- Hide banner
bridge.advertisement.hide_banner()

Banner State

local bridge = require("bridge.bridge")

function init(self)
    bridge.advertisement.on("banner_state_changed", function (_, state)
        -- States: 'loading', 'shown', 'hidden', 'failed'
        print("Banner state changed: ", state)
    end)
end

Interstitial Ads

local bridge = require("bridge.bridge")

-- Check support
local is_supported = bridge.advertisement.is_interstitial_supported()

-- Get current state: 'loading', 'opened', 'closed', 'failed'
local state = bridge.advertisement.interstitial_state()

-- Get/set minimum delay between ads (default: 60 seconds)
local delay = bridge.advertisement.minimum_delay_between_interstitial()
bridge.advertisement.set_minimum_delay_between_interstitial(30)

-- Show interstitial
local placement = "level_complete"  -- optional
bridge.advertisement.show_interstitial(placement)

Interstitial State

local bridge = require("bridge.bridge")

function init(self)
    bridge.advertisement.on("interstitial_state_changed", function (_, state)
        -- States: 'loading', 'opened', 'closed', 'failed'
        print("Interstitial state changed: ", state)

        if state == "opened" then
            -- Your logic
        elseif state == "closed" or state == "failed" then
            -- Your logic
        end
    end)
end

Note: Do not call show_interstitial() at game start. On platforms where this is allowed, ads will be shown automatically.

Rewarded Ads

local bridge = require("bridge.bridge")

-- Check support
local is_supported = bridge.advertisement.is_rewarded_supported()

-- Get current state: 'loading', 'opened', 'closed', 'rewarded', 'failed'
local state = bridge.advertisement.rewarded_state()

-- Get current placement
local placement = bridge.advertisement.rewarded_placement()

-- Show rewarded ad
local placement = "double_coins"  -- optional
bridge.advertisement.show_rewarded(placement)

Rewarded State

local bridge = require("bridge.bridge")

function init(self)
    bridge.advertisement.on("rewarded_state_changed", function (_, state)
        -- States: 'loading', 'opened', 'closed', 'rewarded', 'failed'
        print("Rewarded state changed: ", state)

        if state == "opened" then
            -- Your logic
        elseif state == "rewarded" then
            -- Grant reward to player
        elseif state == "closed" or state == "failed" then
            -- Your logic
        end
    end)
end

Important: Only grant rewards when state is rewarded.

In-App Purchases

local bridge = require("bridge.bridge")

-- Check support
local is_supported = bridge.payments.is_supported()

Purchase Item

local bridge = require("bridge.bridge")

function init(self)
    local id = "coins_100"
    bridge.payments.purchase(id, function (_, purchase)
        -- success
        print("Purchased: ", purchase.id)
    end, function (_, error)
        -- error
    end)
end

Consume Purchase

local bridge = require("bridge.bridge")

function init(self)
    local id = "coins_100"
    bridge.payments.consume_purchase(id, function (_, purchase)
        -- success
    end, function ()
        -- error
    end)
end

Get Catalog

local bridge = require("bridge.bridge")

function init(self)
    bridge.payments.get_catalog(function (_, catalog)
        for key, value in pairs(catalog) do
            local id = value.id
            local price = value.price
            local priceCurrencyCode = value.priceCurrencyCode
            local priceValue = value.priceValue
            print("Product: ", id, " Price: ", price)
        end
    end, function ()
        -- error
    end)
end

Get Purchases

local bridge = require("bridge.bridge")

function init(self)
    bridge.payments.get_purchases(function (_, purchases)
        for key, value in pairs(purchases) do
            local id = value.id
            print("Owned: ", id)
        end
    end, function ()
        -- error
    end)
end

Leaderboards

local bridge = require("bridge.bridge")

-- Leaderboard type: 'not_available', 'in_game', 'native', 'native_popup'
local leaderboard_type = bridge.leaderboards.type

Set Score

local bridge = require("bridge.bridge")

function init(self)
    local leaderboardId = "high_score"
    local score = 1000

    bridge.leaderboards.set_score(leaderboardId, score, function ()
        -- success
    end, function ()
        -- error
    end)
end

Get Entries

Works only when bridge.leaderboards.type equals in_game:

local bridge = require("bridge.bridge")

function init(self)
    local leaderboardId = "high_score"
    local options = {}

    bridge.leaderboards.get_entries(options, function (_, data)
        for key, value in pairs(data) do
            print("ID: ", value.id)
            print("Name: ", value.name)
            print("Photo: ", value.photo)
            print("Score: ", value.score)
            print("Rank: ", value.rank)
        end
    end, function ()
        -- error
    end)
end

Show Native Popup

Works only when bridge.leaderboards.type equals native_popup:

local bridge = require("bridge.bridge")

function init(self)
    local leaderboardId = "high_score"

    bridge.leaderboards.show_native_popup(leaderboardId, function ()
        -- success
    end, function ()
        -- error
    end)
end

Social Features

Share

local bridge = require("bridge.bridge")

function init(self)
    -- Check support
    local is_supported = bridge.social.is_share_supported()

    local options = {
        vk = {
            link = "YOUR_LINK"
        },
        facebook = {
            image = "A base64 encoded image to be shared",
            text = "A text message to be shared."
        },
        msn = {
            title = "A title to display",
            image = "A base64 encoded image or image URL to be shared",
            text = "A text message to be shared."
        }
    }

    bridge.social.share(options, function ()
        -- success
    end, function ()
        -- error
    end)
end

Invite Friends

local bridge = require("bridge.bridge")

function init(self)
    local options = {
        vk = {
            text = "Hello World!"
        },
        facebook = {
            image = "A base64 encoded image to be shared",
            text = "A text message"
        }
    }

    bridge.social.invite_friends(options, function ()
        -- success
    end, function ()
        -- error
    end)
end

Join Community

local bridge = require("bridge.bridge")

function init(self)
    local options = {
        vk = {
            groupId = "YOUR_GROUP_ID"
        },
        ok = {
            groupId = "YOUR_GROUP_ID"
        },
        facebook = {
            isPage = true
        }
    }

    bridge.social.join_community(options, function ()
        -- success
    end, function ()
        -- error
    end)
end

Create Post

local bridge = require("bridge.bridge")

function init(self)
    local options = {
        ok = {
            media = {
                {
                    type = "text",
                    text = "Hello World!"
                },
                {
                    type = "link",
                    url = "https://apiok.ru"
                },
                {
                    type = "poll",
                    question = "Do you like our game?",
                    answers = {
                        { text = "Yes" },
                        { text = "No" }
                    },
                    options = "SingleChoice,AnonymousVoting"
                }
            }
        }
    }

    bridge.social.create_post(options, function ()
        -- success
    end, function ()
        -- error
    end)
end

Add to Favorites

bridge.social.add_to_favorites(function ()
    -- success
end, function ()
    -- error
end)

Add to Home Screen

bridge.social.add_to_home_screen(function ()
    -- success
end, function ()
    -- error
end)

Rate Game

bridge.social.rate(function ()
    -- success
end, function ()
    -- error
end)

Achievements

local bridge = require("bridge.bridge")

-- Check support
local is_supported = bridge.achievements.is_supported()
local is_get_list_supported = bridge.achievements.is_get_list_supported()
local is_native_popup_supported = bridge.achievements.is_native_popup_supported()

Unlock Achievement

local bridge = require("bridge.bridge")

function init(self)
    local options = {
        y8 = {
            achievement = "ACHIEVEMENT_NAME",
            achievementkey = "ACHIEVEMENT_KEY"
        },
        lagged = {
            achievement = "ACHIEVEMENT_ID"
        }
    }

    bridge.achievements.unlock(options, function ()
        -- success
    end, function ()
        -- error
    end)
end

Get List

local bridge = require("bridge.bridge")

function init(self)
    local options = {}
    bridge.achievements.get_list(options, function (_, data)
        for key, value in pairs(data) do
            print("Achievement: ", value)
        end
    end, function ()
        -- error
    end)
end

Show Native Popup

local bridge = require("bridge.bridge")

function init(self)
    local options = {}
    bridge.achievements.show_native_popup(options, function ()
        -- success
    end, function ()
        -- error
    end)
end

Best Practices

1. Always call bridge.platform.send_message("game_ready") when game is fully loaded
2. Subscribe to audio_state_changed and mute/unmute game audio accordingly
3. Subscribe to pause_state_changed and pause/resume game accordingly
4. Show ads at natural breakpoints (level transitions, player death), not during gameplay
5. Check is_supported methods before using platform-specific features
6. Grant rewards only when rewarded ad state is rewarded
7. Use platform-specific options for social features based on bridge.platform.id()
8. Wait for storage callbacks before making sequential storage operations
9. Do not call show_interstitial() at game start - it will be shown automatically where allowed