Skip to content

Latest commit

 

History

History
536 lines (322 loc) · 15.3 KB

README.md

File metadata and controls

536 lines (322 loc) · 15.3 KB
Raw

Ads Wrapper for Defold

Ads Wrapper allows:

  • Use the same interface for working with different advertising services.
  • Advertising mediation - allows you to show ads from different sources.

Supported services:

  • Admob
  • Unity Ads
  • Poki
  • Yandex
  • Yandex Mobile Ads
  • Vk Bridge
  • Applovin Max
  • GameDistribution
  • IronSource

Ads Wrapper also allows you to run multiple networks at the same time. For example Admob and Unity Ads.

You can find more information on the networks

Installation

You can use it in your own project by adding this project as a Defold library dependency. Open your game.project file and in the dependencies field add a link to the ZIP file of a specific release.

Initialization

First you need to make a require for ads_wrapper.ads_wrapper and ads_wrapper.events.

local ads_wrapper = require("ads_wrapper.ads_wrapper")
local events = require("ads_wrapper.events")

Next, you need to register the networks. More details about networks can be found here.

-- Getting our module with networks
local test = require("ads_wrapper.ads_networks.test")
-- Register the first network
local test_1_id = ads_wrapper.register_network(test.network1, {param = "test_param 1"})
-- Register the second network
local test_2_id = ads_wrapper.register_network(test.network2, {param = "test_param 2"})

Next, you need to configure the mediators you need. There are two types: Video and Banner. Video mediator refers to the functions associated with interstitials and rewarded videos. Banner mediator refers to the functions associated with banners. You need to set up only the mediator that you need. For example, Poki does not support banners.

-- Setup video mediator
ads_wrapper.setup_video({{id = test_2_id, count = 2}, {id = test_1_id, count = 2}}, 4)
-- Setup banner mediator
ads_wrapper.setup_banner({{id = test_1_id, count = 1}})

You can read more about mediators here.

Next, you need to initialize ads wrapper.

ads_wrapper.init(true, true, function(response)
    if response.result == events.SUCCESS then
        pprint("Ads wrapper is initialized", response)
    else
        pprint("Something bad happened", response)
    end
end)

In the first two parameters, you can specify the need to initialize the network. First - initilize_video, Second - initilize_banner. This may take time depending on the service. Further, they can be initialized separately, if not done immediately. When an advertisement is called, they will be initialized automatically if it has not been done before.

Almost all functions have a callback parameter. callback - function which takes one response parameter.

Response

The response can be of two types: success and error.

Response is a table:

  • result hash required May be events.SUCCESS or events.ERROR
  • name string optional Network name
  • message string optional Additional information. For example, consists info about error or it may report that the network has already been initialized when init_video_networks is called again.
  • code hash optional Response code. Information that convient to track by code.
  • responses table optional Contains all responses if the function is called for multiple networks. This may be during initialization.
  • was_open table optional Some networks report whether ads was open when calling show_interstitial or show_rewarded.

Also, the response may contain additional information from a specific network.

Module ads_wrapper.events contains useful variables:

  • events.SUCCESS hash("SUCCESS")
  • events.ERROR hash("ERROR")

Response Codes

The response table may have the code. All of them are contained in the ads_wrapper.events module, like events.C_SKIPPED. There are types of codes:

  • events.C_SKIPPED hash("C_SKIPPED") - if the rewarded advertisement was skipped
  • events.C_ERROR_UNKNOWN hash("C_ERROR_UNKNOWN") - an unknown error type is occured
  • events.C_ERROR_AD_BLOCK hash("C_ERROR_AD_BLOCK") - an error is related to the adblock
  • events.C_ERROR_NO_CONNECTION hash("C_ERROR_NO_CONNECTION") - no internet connection

Mediators

Mediators are configured with two functions: ads_wrapper.setup_video and ads_wrapper.setup_banner. The function sets the order which creates the queue.

Options:

  • order table required Ad display order. This is an array that contains objects like {id = network_id, count = 2}.
    • id number required Id that you get when registering a network using ads_wrapper.register_network.
    • count number optional how many times you need to show ads in a row in a queue. Default 1
  • repeat_cut number optional specified if after the first cycle in queue it is necessary to cut off a part of the order. Default: the total number of all networks. Below are examples.

Examples:

  1. Single network

    All other parameters are not needed for one network.

    ads_wrapper.setup_video({{id = test_id_1}})

    Queue: test_1->test_1->test_1->test_1->test_1->

  2. Multiple networks with repeat_cut parameter

    ads_wrapper.setup_video({{id = test_id_1, count = 2}, {id = test_id_2, count = 2}, {id = test_id_1, count = 1}}, 3)

    Queue:

    • 1: test_1->test_1->test_2->test_2->test_1->
    • 2: test_2->test_2->test_1->
    • 3: test_2->test_2->test_1->
    • And so on

    Part of the order is cut off after the first cycle.

  3. Multiple networks without repeat_cut parameter

    repeat_cut automatically becomes 3.

    ads_wrapper.setup_video({{id = test_id_1, count = 1}, {id = test_id_2, count = 2}})

    Queue:

    • 1: test_1->test_2->test_2->
    • 2: test_1->test_2->test_2->
    • 3: test_1->test_2->test_2->
    • And so on

Lua API

In many functions there is a queue of calls. Before calling show_intertitial ads_wrapper will check if the ad has been loaded, and if not, it will load it first. If there is an error somewhere, the queue will break.

ads_wrapper.register_network(network, params)

Registers network. Returns id.

Parameters

  • network table required network module
  • params table required network options. They are different for every network. They can be found in the networks section.

Return

  • id number Network id. It is needed to set up the mediator.

ads_wrapper.setup_video(order, repeat_count)

Setups interstitial and reward mediator. More info here.

Parameters

  • order table required Ad display order. This is an array that contains objects like {id = network_id, count = 2}.
  • repeat_cut number optional specified if after the first cycle in queue it is necessary to cut off a part of the order. Default: the total number of all networks.

ads_wrapper.setup_banner(order, repeat_count, _banner_auto_hide)

Setups banner mediator. More info here.

Parameters

  • order table required Ad display order. This is an array that contains objects like {id = network_id, count = 2}.
  • repeat_cut number optional specified if after the first cycle in queue it is necessary to cut off a part of the order. Default: the total number of all networks.
  • _banner_auto_hide boolean optional The banner will be automatically hidden if hide_banner was called after show_banner, but the banner did not have time to load. Default: false

ads_wrapper.init(initilize_video, initilize_banner, callback)

Initializes ads_wrapper. Callback consists responses field.

Queue: check_connection->request_idfa->init

Parameters

  • initilize_video boolean optional check if need to initialize video networks
  • initilize_banner boolean optional check if need to initialize banner networks
  • callback function optional callback with response.

ads_wrapper.init_video_networks(callback)

Initialize video networks.

Queue: check_connection->request_idfa->init

Parameters

  • callback function optional callback with response

ads_wrapper.init_banner_networks(callback)

Initialize banner networks.

Queue: check_connection->request_idfa->init

Parameters

  • callback function optional callback with response

ads_wrapper.load_rewarded(callback)

Loads rewarded ads for next network.

Queue: check_connection->request_idfa->init->load_rewarded

Parameters

  • callback function optional callback with response

Return

  • id integer|nil id to cancel execution

ads_wrapper.show_rewarded(callback)

Shows rewarded ads for next network. Callback contain a special code field with events.C_SKIPPED if the user skipped the ad.

Queue: check_connection->request_idfa->init->load_rewarded->show_rewarded

Parameters

  • callback function optional callback with response.

Return

  • id integer|nil id to cancel execution

ads_wrapper.load_interstitial(callback)

Loads interstitial ads for next network.

Queue: check_connection->request_idfa->init->load_interstitial

Parameters

  • callback function optional callback with response

Return

  • id integer|nil id to cancel execution

ads_wrapper.show_interstitial(callback)

Shows interstitial ads for next network.

Queue: check_connection->request_idfa->init->load_interstitial->show_interstitial

Parameters

  • callback function optional callback with response

Return

  • id integer|nil id to cancel execution

ads_wrapper.load_banner(callback)

Loads banner for for next network.

Queue: check_connection->request_idfa->init->load_banner

Parameters

  • callback function optional callback with response

Return

  • id integer|nil id to cancel execution

ads_wrapper.show_banner(callback)

Shows setup banner for next network. Hides the previous banner if it was displayed.

Queue: check_connection->request_idfa->init->load_banner->show_banner

Parameters

  • callback function optional callback with response

Return

  • id integer|nil id to cancel execution

ads_wrapper.hide_banner(callback)

Hides setup banner for current network.

Parameters

  • callback function optional callback with response

ads_wrapper.unload_banner(callback)

Unloads banner for current networks.

Parameters

  • callback function optional callback with response

ads_wrapper.is_banner_setup()

Check if the banner mediator is set up

Return

  • value boolean

ads_wrapper.is_video_setup()

Check if the interstitial and rewarded video mediator is set up

Return

  • value boolean

ads_wrapper.is_initialized()

Check if ads wrapper is initiailzed

Return

  • value boolean

ads_wrapper.is_internet_connected()

Checks for internet connection

Return

  • value boolean

ads_wrapper.is_interstitial_loaded(check_current)

Check if the interstitial video is loaded. Default checks the next network in mediator.

Parameters

  • check_current boolean optional if need check current network. Default false

Return

  • value boolean

ads_wrapper.is_rewarded_loaded(check_current)

Check if the rewarded video is loaded. Default checks the next network in mediator.

Parameters

  • check_current boolean optional if need check current network. Default false

Return

  • value boolean

ads_wrapper.is_banner_loaded(check_current)

Check if the banner is loaded. Default checks the next network in mediator.

Parameters

  • check_current boolean optional if need check current network. Default false

Return

  • value boolean

ads_wrapper.get_current_network(check_banner)

Returns the current network pointed to by mediator Default returns for the video mediator

Parameters

  • check_banner boolean optional if need to return mediator for banners. Default false

Return

  • network table|nil

ads_wrapper.get_next_network(check_banner)

Returns the next network pointed to by mediator Default returns for the video mediator

Parameters

  • check_banner boolean optional if need to return mediator for banners. Default false

Return

  • network table|nil

ads_wrapper.clear_networks()

Remove all registered networks

ads_wrapper.cancel(id)

Сancel execution of the next step in the queue. For example, if you cancel show_interstitial while the ad is loading, then it will not be shown.

Parameters

  • id number required queue id received from the function

Constants

Constants are used to set network parameters

  • T_REWARDED hash("T_REWARDED")
  • T_INTERSTITIAL hash("T_INTERSTITIAL")
  • T_BANNER hash("T_BANNER")

Platform

This module can be used in network settings.

local platform = require("ads_wrapper.platform")

Constants:

  • PL_ANDROID hash("PL_ANDROID")
  • PL_IOS hash("PL_IOS")
  • PL_HTML5 hash("PL_HTML5")
  • PL_OTHER hash("PL_OTHER")

platform.is_same(pl_value)

Parameters

  • pl_value hash required One of the constants

Сheck if the platform is correct

Return

  • value boolean

platform.get()

Returns current hash platform

Return

  • value hash

Networks

You can use existing networks or create your own. More information can be found at the links:

Network Creation

You can create your own network. It is best to look at already made networks.

Debug mode

You can include output to the console of all operations that are done when calling functions with the queue.

local events = require("ads_wrapper.events")
local queue = require("ads_wrapper.queue")

queue.set_verbose_mode(events.V_ALL)

Constants:

  • events.V_NONE hash("V_NONE") Output nothing. Default value.
  • events.V_ERROR hash("V_ERROR") Show all errors
  • events.V_SUCCESS hash("V_SUCCESS") Show all success responses
  • events.V_ALL hash("V_ALL") Show all messages

Credits

Made by PotatoJam.

For example used:

Dirty Larry

Druid

License

MIT license.