“This plugin is not endorsed or sponsored by Unity Technologies. This is an independent, unofficial plugin. UNITY and the Unity logo are Unity Technologies’ registered trademarks in the US and other countries--All rights reserved.“

DefVideoAds (plugin for Unity ADS)

This is UnityAds native extension for Defold engine. The extension supports iOS 13.0 and later, and Android.

Installation

To use this library in your Defold project, add the needed version URL to your game.project dependencies from Releases

Example

See the example folder for understand how to use extension. Especially ui.gui_script file.

LUA Api

Please read the Unity Ads 4.19.0 Android API documentation and iOS Objective-C API documentation.

Methods

unityads.request_idfa()

unityads.request_idfa()
-- iOS only method that shows IDFA request popup.
-- On Android it always fire callback with MSG_IDFA/EVENT_NOT_SUPPORTED
-- should be called before initialization

unityads.initialize(game_id, callback)

unityads.initialize(game_id, callback, test_mode)

Original Docs iOS Android

local function defunityads_callback(self, message_id, message)
...
end
...
unityads.initialize("1401815", defunityads_callback)
 -- `test_mode` is optional parameter:
unityads.initialize("1401815", defunityads_callback, true)

If a callback was set beforehand, omitting the callback or passing nil preserves it:

unityads.set_callback(defunityads_callback)
unityads.initialize("1401815")
-- or:
unityads.initialize("1401815", nil, true)

unityads.set_callback(callback)

unityads.set_callback(defunityads_callback) -- set callback
unityads.set_callback(nil) -- remove callback
unityads.set_callback() -- remove callback

unityads.set_debug_mode(is_debug)

Original Docs iOS Android

unityads.set_debug_mode(true) -- set debug mode
unityads.set_debug_mode(false) -- set debug mode

unityads.get_debug_mode()

Original Docs iOS Android

local is_debig_mode = unityads.getDebugMode() -- Returns true if current mod is debug

unityads.is_initialized()

Original Docs iOS Android

local is_initialized = unityads.is_initialized() -- Returns `true` if Unity ADS initialized

unityads.is_supported()

Original Docs iOS Android

local is_supported = unityads.is_supported() -- Returns `true` if Unity Ads is supported by the current device

unityads.get_version()

local version = unityads.get_version() -- Returns the Unity Ads SDK version as a string.

unityads.show(placement_id)

unityads.show("rewardedVideo") -- show rewardedVideo

The extension automatically mutes the Defold master sound group when an ad starts and restores the previous mute state when the ad completes, is skipped, or fails.

unityads.load(placement_id)

unityads.load("rewardedVideo") -- load rewardedVideo

unityads.load_banner(placement_id)

unityads.load_banner(placement_id, banner_width, banner_height)

unityads.load_banner("banner") -- load banner, by default width = 320, height = 50
unityads.load_banner("banner", 320, 50) -- load banner

unityads.unload_banner()

unityads.unload_banner() -- destroy the loaded banner

unityads.show_banner()

unityads.show_banner() -- show or restore the loaded banner

unityads.hide_banner()

unityads.hide_banner() -- temporarily hide the banner without unloading it

Use hide_banner() when the same banner will be shown again. Use unload_banner() only when the banner is no longer needed; load a new banner before calling show_banner() again.

unityads.set_banner_position(position)

unityads.set_banner_position(position) -- set position of the banner
-- default value is unityads.BANNER_POSITION_TOP_CENTER

--possible positions:
unityads.BANNER_POSITION_TOP_LEFT
unityads.BANNER_POSITION_TOP_CENTER
unityads.BANNER_POSITION_TOP_RIGHT
unityads.BANNER_POSITION_BOTTOM_LEFT
unityads.BANNER_POSITION_BOTTOM_CENTER
unityads.BANNER_POSITION_BOTTOM_RIGHT
unityads.BANNER_POSITION_CENTER

Constants

local function defunityads_callback(self, message_id, message)
...
end

Message types

--possible values for `message_id` :
unityads.MSG_INIT
unityads.MSG_SHOW
unityads.MSG_LOAD
unityads.MSG_BANNER
unityads.MSG_IDFA

unityads.MSG_INIT

local function defunityads_callback(self, message_id, message)
  if message_id == unityads.MSG_INIT then
    if message.event == unityads.EVENT_COMPLETED then
        -- message = {placement_id = "string", ...}
    elseif message.event == unityads.EVENT_SDK_ERROR then
        -- message = {code = int, error = "error message string"}
        if message.code == unityads.ERROR_INTERNAL then
            -- initialization failed due to environment or internal services
        elseif message.code == unityads.ERROR_INVALID_ARGUMENT then
            -- initialization failed due to invalid argument(e.g. game ID)
        elseif message.code == unityads.ERROR_AD_BLOCKER_DETECTED then
            -- initialization failed due to url being blocked
        end
    elseif message.event == unityads.EVENT_JSON_ERROR then
        -- message = {error = "error message string"}
    end
  end
end

unityads.MSG_SHOW

local function defunityads_callback(self, message_id, message)
  if message_id == unityads.MSG_SHOW then
    if message.event == unityads.EVENT_COMPLETED then
      -- message = {placement_id = "string"}
      -- An event that indicates that the ad was played entirely.
    elseif message.event == unityads.EVENT_SKIPPED then
        -- message = {placement_id = "string"}
        -- An event that indicates that the user skipped the ad.
    elseif message.event == unityads.EVENT_START then
        -- message = {placement_id = "string"}
        -- UnityAds has started to show ad with a specific placement.
    elseif message.event == unityads.EVENT_CLICKED then
        -- message = {placement_id = "string"}
        -- UnityAds has received a click while showing ad with a specific placement.
    elseif message.event == unityads.EVENT_SDK_ERROR then
        -- message = {code = int, error = "error message string", placement_id = "string"}
        if message.code == unityads.ERROR_NOT_INITIALIZED then
            -- show failed due to SDK not initialized.
        elseif message.code == unityads.ERROR_NOT_READY then
            --show failed due to placement not being ready.
        elseif message.code == unityads.ERROR_VIDEO_PLAYER then
            -- show failed due to video player.
        elseif message.code == unityads.ERROR_INVALID_ARGUMENT then
            -- show failed due to invalid arguments.
        elseif message.code == unityads.ERROR_NO_CONNECTION then
            -- show failed due to internet connection.
        elseif message.code == unityads.ERROR_ALREADY_SHOWING then
            -- show failed due to ad is already being showen.
        elseif message.code == unityads.ERROR_INTERNAL then
            -- show failed due to environment or internal services.
        elseif message.code == unityads.ERROR_TIMEOUT then
            -- Error related to an Ad being unable to show within a specified time frame
        end
    elseif message.event == unityads.EVENT_JSON_ERROR then
        -- message = {error = "error message string"}
    end
  end
end

unityads.MSG_LOAD

local function defunityads_callback(self, message_id, message)
  if message.event == unityads.EVENT_LOADED then
      -- message = {placement_id = "string"}
      -- Load request has successfully filled the specified placementId with an ad that is ready to show.
  elseif message.event == unityads.EVENT_SDK_ERROR then
      -- message = {code = int, error = "error message string", placement_id = "string"}
      if message.code == unityads.ERROR_NOT_INITIALIZED then
          -- Error related to SDK not initialized
      elseif message.code == unityads.ERROR_INTERNAL then
          -- Error related to environment or internal services
      elseif message.code == unityads.ERROR_INVALID_ARGUMENT then
          -- Error related to invalid arguments
      elseif message.code == unityads.ERROR_NO_FILL then
          -- Error related to there being no ads available
      elseif message.code == unityads.ERROR_TIMEOUT then
          -- Error related to there being no ads available
      end
  elseif message.event == unityads.EVENT_JSON_ERROR then
      -- message = {error = "error message string"}
  end
end

unityads.MSG_BANNER

local function defunityads_callback(self, message_id, message)
  if message.event == unityads.EVENT_LOADED then
      -- message = {placement_id = "string", width = int, height = int}
      -- Banner is loaded and ready to be placed in the view hierarchy.
      -- width and height are screen pixels, matching window.get_size().
  elseif message.event == unityads.EVENT_LEFT_APPLICATION then
      -- message = {placement_id = "string"}
      -- Banner links outside the application.
  elseif message.event == unityads.EVENT_CLICKED then
      -- message = {placement_id = "string"}
      -- Banner is clicked.
  elseif message.event == unityads.EVENT_DID_SHOW then
      -- message = {placement_id = "string", width = int, height = int}
      -- The displayed banner size in screen pixels.
  elseif message.event == unityads.EVENT_SDK_ERROR then
      -- message = {code = int, error = "error message string", placement_id = "string"}
      if message.code == unityads.ERROR_UNKNOWN then
          -- Unknown error 
      elseif message.code == unityads.ERROR_NATIVE then
          -- Error related to native
      elseif message.code == unityads.ERROR_WEBVIEW then
          -- Error related to webview
      elseif message.code == unityads.ERROR_NO_FILL then
          -- Error related to there being no ads available
      end
  elseif message.event == unityads.EVENT_JSON_ERROR then
      -- message = {error = "error message string"}
  end
end

Banner dimensions use Defold screen coordinates. To reserve the equivalent height in a GUI scene:

local _, screen_height = window.get_size()
local banner_gui_height = message.height * gui.get_height() / screen_height

For banners anchored at the top or bottom, use window.get_safe_area() if the GUI extends into the unsafe area. Add inset_top or inset_bottom before converting the reserved height to GUI coordinates.

unityads.MSG_IDFA

local function defunityads_callback(self, message_id, message)
  if message.event == unityads.EVENT_NOT_SUPPORTED then
      -- IDFA isn't supported
  elseif message.event == unityads.EVENT_STATUS_AUTORIZED then
  elseif message.event == unityads.EVENT_STATUS_DENIED then
  elseif message.event == unityads.EVENT_STATUS_NOT_DETERMINED then
  elseif message.event == unityads.EVENT_STATUS_RESTRICTED then
  elseif message.event == unityads.EVENT_JSON_ERROR then
      -- message = {error = "error message string"}
  end
end

---

If you have any issues, questions or suggestions please create an issue or contact me: me@agulev.com