Corona Plugin Quick Start

The TUNE plugin for Corona allows you to manage marketing campaigns, engage the right audiences, and grow your business with the partners and channels that make it possible.

Install

To use this plugin, add these entries into the plugins table of build.settings. When added, the build server will integrate the plugin during the build phase.

settings =
{
    plugins =
    {
        ["plugin.tune"] =
        {
            publisherId = "com.tune",
            supportedPlatforms = { iphone=true, android=true }
        },
        ["plugin.google.play.services"] =
        {
            publisherId = "com.coronalabs",
            supportedPlatforms = { android=true }
        },
        ["shared.android.support.v4"] =
        {
            publisherId = "com.coronalabs",
            supportedPlatforms = { android=true }
        },
    },
}

For Android, the following permissions/features/activities are automatically added when using this plugin:

android
{
    usesPermissions =
    {
        "android.permission.INTERNET",
        "android.permission.ACCESS_NETWORK_STATE",
    },
    applicationChildElements =
    {
        [[
            <receiver android:name="com.tune.TuneTracker">
                <intent-filter>
                    <action android:name="com.android.vending.INSTALL_REFERRER" />
                </intent-filter>
            </receiver>
        ]]
    },
},

Install for Corona Enterprise

If you're using Corona Enterprise, please follow these install steps instead.
For Android:

  1. Download the plugin.tune.jar file.
  2. In Android Studio, create a libs folder inside your app folder and add the JAR to it.
  3. In your app’s build.gradle, add the TUNE plugin’s required dependencies:
dependencies {
    compile fileTree(dir: 
"$coronaEnterpriseDir/Corona/android/lib/Corona/libs", include: '*.jar')
    compile fileTree(dir: 'libs', include: '*.jar')
    compile 'com.google.android.gms:play-services-basement:9.2.1'
    compile 'com.tune:tune-marketing-console-sdk:4.4.0'
}

Add the following to your AndroidManifest.xml:

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

<application>
   <receiver android:name="com.tune.TuneTracker">
       <intent-filter>
           <action android:name="com.android.vending.INSTALL_REFERRER" />
       </intent-filter>
   </receiver>
</application>

For iOS:

  1. Download the libplugin_tune.a file.
  2. In your Xcode project, add a local reference to the library. In your app target, select General -> Linked Frameworks and Libraries -> ‘+’ sign -> Add Other -> select the libplugin_tune.a file.
  3. Corona has a bug where adding a local library messes up the Corona library path by adding quotes around it. In your app’s Build Settings -> Library Search Paths, remove the quotes around $(SRCROOT)/CoronaEnterprise/Corona/ios/lib.
  4. Add the CoreSpotlight (mark as optional), CoreTelephony, libz.dylib and iAd frameworks to your app’s General -> Linked Frameworks and Libraries.

Implementation

  1. Reference the plugin: local tune = require "plugin.tune".
  2. Call init with your TUNE advertiser ID and conversion key: tune.init( "advertiser_id", "conversion_key" ).
  3. Add a listener for the applicationStart and applicationOpen events to measure a session from app start and app resumes. This will measure opens and installs in TUNE.
local function onSystemEvent( event )
  if event.type == "applicationStart" then
    -- Measure TUNE session on app start
    tune.measureSession()
  elseif event.type == "applicationOpen" and event.url then
    -- Capture app re-opened from deep link in TUNE
    tune.setDeepLink( event.url )
    tune.measureSession()
  end
Runtime:addEventListener( "system", onSystemEvent )

Add a setter for capturing the deep link from the launchArgs, if any.

-- Set launch url in TUNE
local launchArgs = ...
if launchArgs and launchArgs.url then
  -- Capture app launched from deep link in TUNE
  library.setDeepLink( launchArgs.url )
end

Example

An example of a main.lua with TUNE plugin implementation:

local tune = require "plugin.tune"


tune.init( "advertiser_id", "conversion_key" )


local function onSystemEvent( event )
  print( "System event name and type: " .. event.name, event.type )
  if event.type == "applicationStart" then
    -- Measure TUNE session on app start
    tune.measureSession()
  elseif event.type == "applicationOpen" and event.url then
    -- Capture app re-opened from deep link in TUNE
    tune.setDeepLink( event.url )
    tune.measureSession()
  end
end

Runtime:addEventListener( "system", onSystemEvent )

-- Set launch url in TUNE
local launchArgs = ...
if launchArgs and launchArgs.url then
  -- Capture app launched from deep link in TUNE
  tune.setDeepLink( launchArgs.url )
end

Events

To measure events with TUNE, use the measureEvent method, passing in either a string as the event name like the following:

tune.measureEvent( “your_event_name” )

or a table mapping of the event. This example lists all the possible event values TUNE accepts:

tune.measureEvent( {
  name = "purchase", // Name is the only required param for events
  revenue = 0.99, // Rest are optional
  currency = "CAD",
  advertiserRefId = "123", // Must be unique per event
  eventItems = { // Can be any number of event items
    {
      name = "coins", // Name is the only required param for event items
      unitPrice = 0.99, // Rest are optional
      quantity = 3,
      revenue = 4.99,
      attribute1 = "attr1",
      attribute2 = "attr2",
      attribute3 = "attr3",
      attribute4 = "attr4",
      attribute5 = "attr5"
    },
    {
      name = "socks",
    }
  },
  contentType = "some_content_type",
  contentId = "some_content_id",
  date1 = os.time(),
  date2 = os.time( {year = 2015, month = 1, day = 1} ),
  level = 5,
  quantity = 3,
  searchString = "stuff",
  rating = 3.5,
  attribute1 = "some_string_1",
  attribute2 = "some_string_2",
  attribute3 = "some_string_3",
  attribute4 = "some_string_4",
  attribute5 = "some_string_5",
} )

API

The following is a a comprehensive list of methods supported by the TUNE Corona plugin:

  • init(String advertiserId, String conversionKey) - Initializes TUNE plugin. Required before any other calls.
  • measureSession() - Measures the start of an app session, used to determine app opens and installs.
  • measureEvent(String eventName) - Measures a custom event occurrence.
  • measureEvent(Table tuneEvent) - Measures a custom event, with support for extra parameters.
  • setDebugMode(boolean enable) - Enables debug mode for logging and verbose server responses.
  • setDeepLink(String deepLinkUrl) - Sets the deep link used to open the app, for measuring re-engagement.
  • setExistingUser(boolean existingUser) - Sets whether the user existed prior to installing the app with TUNE, so that they are not counted as a new install the first time they are seen by TUNE.
  • setListener(listener) - Sets a listener for server response. Callback events are ‘didSucceedWithData’ with response, ‘didFailWithError' with response
  • setPackageName(String packageName) - Sets the package name of the app as seen by TUNE. Not necessary if the package name/bundle identifier of the app matches the package name value in TUNE dashboard.
  • setShouldAutoCollectDeviceLocation(boolean collectLocation) - Sets whether the TUNE plugin should auto-collect device location if location is enabled.
  • setUserId(String userId) - Sets user id value that your system has assigned the user, for reporting purposes.
  • checkForDeferredDeeplink(listener) - Sets a listener for whether TUNE found a deferred deep link for this install. Callback events are ‘didReceiveDeeplink’ with url, ‘didFailDeeplink’ with error message.

No Comments

Leave a reply