Adverty

Documentation

Change log

  • ● General bug fixes and performance enhancements

Known Issues

In Unity 2019.2, Unity and Native graphic device is not synced from start generating an error log OPENGL NATIVE PLUG-IN ERROR: GL_INVALID_ENUM. This does not affect the functionality and will only be logged once. 

Requirements

  • ● Officially released Unity versions 5.6.3 or later.
  • ● “32-bit Display Buffer” set to true, under “Resolution and Presentation”
  • ● Compute shader compatible devices
    • Windows PC with Directx 11 or 12 graphics API and Shader Model 5.0 GPU
    • macOS and iOS using Metal graphics API
    • Modern Open GL platforms (Open GL 4.3 for windows and Open GL ES 3.1 for Android)
    • Vulkan for Android
    • Preview Linux 
  • ● Android 5.0 (build support from Android 4.0) together with above requirements
  • ● iOS 8 together with above requirements

If you are building an Android application and want to test your application in the Unity editor, it is a requirement to no graphics emulation and to do that you need to check “No Emulation” in Edit -> Graphics Emulation -> No Emulation. This is required to be set each time you start Unity.

Setup SDK

Import the SDK

● Download the unity package from the SDK repository and import it to your project. This will enable quick updating of SDK.

Setup the SDK

  • ■ Click the dropdown Adverty > Settings and select the platform for your application (AR, VR or Mobile). Then add the API key generated in the portal.
    release_mode
    Then call the AdvertySDK.Init() with parameters to start an Adverty session.
  • ■ NOTE: To start earning revenue, remember to publish your application in the portal at adverty.com to set the application to “Live”. Without this the application will receive sandbox campaigns.

Set correct MainCamera

  • ■ Set the correct Main Camera through AdvertySettings.SetMainCamera(Camera camera). AdvertySDK incorporates camera and rendering calculations on the main camera. Use this method to specify the main game camera to the AdvertySDK. This is important to ensure revenue for your ad units.

Enable Adverty Debug

■ Go to Adverty > Debug and check “Enable Adverty Logs” to enable debug logs from the AdvertySDK for testing purposes.

When you create a new app through the Portal the app will be set into “Sandbox”-mode. This means that you will retrieve sample campaigns in your app and inside the Unity Editor. Depending on if your unit allows interaction or not it will look like below image where the left does not allow interaction and the right does.demo

Lazy Load

■ Go to Adverty > Settings and yo have an option “Allow Lazy Load”. As default it is enabled. This feature helps you to optimize loading of ads. It will try to load ads as your player approaches the adunits. Each adunit also has an option “Disable Lazy Load” which overrides the global setting.

Depending on how adunits is used in your game you might want to disable Lazy Load for a certain unit. As an example if you have a unit which is always visible you can disable Lazy Load for that unit. However, if you have an adunit which is only visible to users after some exploration of the map lazy load will help you to activate it only when users approaches the adunit in question.

ProGuard Rules

If you are using ProGuard for Android there is a set of rules that needs to be used to maintain the AdvertySDK in the building process.

-keep class com.unity3d.player.**{ *; }
-keep class com.adverty.**{ *; }

Campaign Types

● Attract: This stage will support static or animated campaigns. Revenue is based on CPM model

● Engage: This stage will support viewable and interactable content. For example videos and 360 videos. Revenue is based on a combination of a CPM and CPC model

● Commit: This stage will support actions of the user. For example download an app or register on a website. Revenue is based on a combination of a CPM, CPC and CPA model.

Unit.prefab

3 settings will affect the unit behavior.

● Allow Interaction: If the unit can be interactable and is allowed to be served Engage campaigns. This enables higher revenue possibilities.

● Allow Animation: If the unit can display both animated and static campaigns in the Attract stage.

● Immediate Activation: Immediate activation allows refreshes on ad units to happen immediately instead of when ad unit is not being rendered. First activation is not affected by this setting.

● Shader Type: Two shader types can be used. Unlit type will not be affected by lighting and will show the ad unit with the campaigns “true” colors. Lit type will be affected by lighting in the scene.

Shader

Interactable ads (currently only available for AR and mobile):

With “Allow Interaction” enabled it is possible but not guaranteed to receive an interactable ad. The AdvertyEvents.UnitActivationEvent includes information of campaign delivered. An interactable ad will provide one campaign including up to all 3 stages of content (Attract, Engage and Commit). It starts with the Attract stage, but when the unit is interacted with it will iterate through the different stages described above. Revenue will be generated based on a combination of CPM, CPC and CPA models.

To interact with a unit the interact function must be called. What will trigger the interaction is up to you. For performance reasons a mesh collider is not attached to the unit prefab by default.

void YourIntearctionEvent()
{
	unit.Interact();
}

Setup AdUnits

● Add an ad unit to your scene

○ Locate the Unit.prefab in Assets/adverty/Prefabs/ in the project window hierarchy.

○ Drag the prefab into the scene and position it as you do with any regular game objects in Unity.

○ Snap the ad unit to a surface.

  • ■ The ad unit can be attached to any surface by activating the “Snap to surface” checkbox in the top left corner of the preview window. When the ad unit is selected, click on a desired surface to attach the ad unit to it. This will adjust the position and rotation of the ad unit to match the surface.

Surface

● Ad unit settings

It is possible to add different meshes to the unit, however it has to be an Adverty generated mesh. The package includes a standard and flat UnitMesh (Adverty/Resources/Meshes). It is also possible to generate and store new meshes with different bending properties. Click on “Create Mesh” in the unit editor to access this functionality. The new mesh is bendable in one axis at the time (X-axis or Y-axis) and in either direction (concave or convex). Click the “Save mesh” button to store this mesh somewhere in the project folder. This generated mesh is reusable on any ad unit.

Convex_x

Convex_y

Concave_y

Concave_x

○ VR only: In the SceneContext™ section, set the properties of the ad unit according to the context of the surrounding scene. Try to be as specific as possible to optimize the ad relevance. This will maximize the eCPM and your revenue. Note that some context settings have the option to select more than one predefined value.

VR

● Test your ad units with real-time impression indicator

○ The ImpViz™-component is a real-time impression indicator that shows when ad units placed in the scene generates impressions. This helps you optimize the monetization potential of each ad unit. Remember to remove the ImpViz-component before publishing you application.

○ Locate the impVizComponent in the Adverty.dll plugin and attach it to the adUnit gameObject that you want to test. If you want to test all adUnits in the scene go to Adverty->Debug and click “Add ImpViz component to all units”.

○ When playing the application in Unity the ad units with impViz component attached will tint with impression color when the first ad impression is registered and tint with bounce back color each time it registers an impression after that. This gives a good understanding of how the ad unit should be designed and placed in the scene to generate impressions.

Scripting API

Activate AdvertySDK

To activate the AdvertySDK you need to call AdvertySDK.Init(). Calling Init without any of the optional parameters will use the current configuration set on AdvertySettings and trigger an SDK sign in.

Example 1 with only required parameters:

public class ActivateAdvertyExampleClass : MonoBehaviour
{
    void Start()
    {
        UserData userData = new UserData(AgeSegment.Unknown, Gender.Unknown);
        Adverty.AdvertySDK.Init(userData);
    }
}

Example 2 with optional parameters:

public class ActivateAdvertyExampleClass : MonoBehaviour
{
    void Start()
    {
        string apiKey = YOUR_API_KEY;
        Adverty.AdvertySettings.Mode platform =
        Adverty.,AdvertySettings.Mode.Mobile;
        bool restrictPersonalData = false;
        UserData userData = new UserData(AgeSegment.Unknown, Gender.Unknown);
        Adverty.AdvertySDK.Init(apiKey, platform, restrictPersonalData);

    }
}

You can add custom behaviours to when an Adverty Session Activates or fails to activate by using AdvertyEvents.AdvertySessionActivated and/or AdvertyEvents.AdvertySessionActivationFailed.

Deactivate AdvertySDK

To deactivate the AdvertySDK you need to call AdvertySDK.Terminate(). This will terminate all processes related to the AdvertySDK. To start it again call AdvertySDK.Init().

public class DeactivateAdvertyExampleClass: MonoBehaviour
{
    void Start()
    {
        Adverty.AdvertySDK.Terminate();
    }
}

Programmatic Set up of AdUnits

To instantiate units during runtime you can of course instantiate the unit.prefab but more importantly you can use the Adverty.UnitFactory class.

Adverty. UnitFactory. Create  will return a unit gameobject with the specified configuration and the optional parameters Mesh and GameObject name.

Example without optional parameters:

public class UnitInstantiateExampleClass : MonoBehaviour
{
    void Start()
    {
        Adverty.AdUnit.Configuration config = new Adverty.AdUnit.Configuration();
        config.MeshData.Size = 1f;
        config.MeshData.Ratio = Adverty.AdUnit.MeshData.UnitRatio.Box;
        config.Behavior.AllowInteraction = true;
        GameObject unit = Adverty.AdUnit.UnitFactory.Create(config);
    }
}

Example with optional parameters:

public class UnitInstantiateExampleClass : MonoBehaviour
{
    public Mesh bentAdvertyMesh;
    void Start()
    {
        Adverty.AdUnit.Configuration config = new Adverty.AdUnit.Configuration();
        config.MeshData.Size = 1f;
        config.MeshData.Ratio = Adverty.AdUnit.MeshData.UnitRatio.Box;
        config.Behavior.AllowInteraction = true;
        GameObject unit = Adverty.AdUnit.UnitFactory.Create(config, bentAdvertyMesh, "CustomName");
    }
}

Adverty Settings

AdvertySettings.Platform

If you have multiple modes in a game. For example a 360 view and a VR mode, it is possible to switch the platform of the Adverty SDK.

Example:

public class ChangeAdvertyPlatformExample : MonoBehaviour
{
    void Start()
    {
        Adverty.AdvertySettings.Platform = Adverty.AdvertySettings.Mode.Mobile;
    }
}

AdvertySettings.UserData

If you want to provide user data to the AdvertySDK to improve targeting and eCPM for the campaigns you can set it in AdvertySettings.UserData.

Example:

public class AddUserDataExample : MonoBehaviour
{
    void Start()
    {
         UserData userData = new UserData(AgeSegment.Unknown, Gender.Unknown);
    }
}

AdvertySettings.restrictUserData

If you want to block the AdvertySDK from collecting personal data from the user you can set restrictUserData to true. This will reduce the potential demand and reduce the overall revenue.

Example:

public class RestrictUserDataExample : MonoBehaviour
{
    void Start()
    {
        Adverty.AdvertySettings.RestrictUserData = true;
    }
}

AdvertySettings.APIKey

It is possible to set API key during runtime.

public class SetAPIKeyRuntimeExampe : MonoBehaviour
{
    void Start()
    {
        Adverty.AdvertySettings.APIKey = YOUR_API_KEY;
    }
}

AdvertySettings.SetMainCamera (Camera camera)

Adverty SDK has an automatic detection for game camera, but it is possible to override that.

Example:

public class OverrideAdvertyCameraExample : MonoBehaviour
{
    void Start()
    {
        Adverty.AdvertySettings.SetMainCamera(Camera.main);
    }
}

AdvertySettings.IsLazyLoadAllowed

Adverty SDK has Lazy Load enabled as default but in some games it where units are always visible or reused in multiple places it is not recomended to use Lazy load. In those situation you can disable it by setting it to false before calling AdvertySDK.Init.

Example:

public class OverrideAdvertyCameraExample : MonoBehaviour
{
    void Start()
    {
        Adverty.AdvertySettings.IsLazyLoadAllowed = false;
Adverty.AdvertySDK.Init(UserData userData);
    }
}

AdUnit.Configuration

Public Fields

MeshData Containing fields specifying size and shape of unit mesh
SceneContext Containing fields specifying the target and type of the unit
Behavior Containing fields specifying the behavior of the unit during a run session

AdUnit.MeshData

Public Fields

Size Worldscale scale value used in unit transform
MatchWidthOrHeight Matching side (X or Y) for size value in transform
Ratio Ratio used for unit mesh

Enums

WidthHeight

Width Match meshData.size to X-field in unit transform
Height Match meshData.size to Y-field in unit transform

UnitRatio

Box Aspect ratio 1,2:1
Portrait Aspect ratio 1:2
Landscape Aspect ratio 16:9
WideLandscape Aspect ratio 97:25

 

AdUnit.SceneContext

Public Methods

void AddLocation(Location) Add specified location from locations
void RemoveLocation(Location) Remove specified location from locations

Public Fields

Lighting Value specifying the lighting conditions around the unit
Locations Value specifying the type of location the unit is located in
Setting Value specifying the setting the unit is located in
Size Value specifying the relative size of the unit in the scene
Time Value specifying the time of day the unit is present in
Period Value specifying the time period the unit is present in

Enums

SceneLighting

Unspecified Not specified scene lighting
Light Scene lighting around unit is light
Dark Scene lighting around unit is dark
Other Scene lighting around unit something else

Location

Forest Unit is located in a forest environment
Desert Unit is located in a dessert environment
City Unit is located in a city environment
Suburb Unit is located in a suburb environment
Industrial Unit is located in an industrial environment
Space Unit is located in a space environment
Ocean Unit is located in an ocean environment
Arena Unit is located in an arena environment
Other Unit is located in some other environment

AdSetting

Unspecified Unit setting is not specified
Indoor The setting of the unit is indoor
Outdoor The setting of the unit is outdoor
Other The setting of the unit some something else

UnitSize

S Unit relative size is comparable to a sticker
M Unit relative size is comparable to a poster
L Unit relative size is comparable to a billboard

SceneTime

Unspecified Scene time around the unit is not specified
Day Scene time around the unit is day
Night Scene time around the unit is night
Other Scene time around the unit is something else

TimePeriod

Unspecified Unit is located in an unspecified time period
Past Unit is located in a past time period
Present Unit is located in a present time period
Future Unit is located in a future time period
Other Unit is located in some other time period

 

AdUnit.Behavior

Public Fields

ImmediateActivation Specifying if a refreshing of a unit can update campaign when visible to user
AllowInteraction Specifying if interactable campaings are allowed on unit
AllowAnimatinon Specifying if animated attract stage campaigns are allowed on unit

Adverty Events

AdvertyEvents.AdvertySessionActivated

AdvertySessionActivated fires when an AdvertySession is created successfully.  Best practice should be to start initiating units when you have an activated session.

void Start()
{
    Adverty.AdvertyEvents.AdvertySessionActivated += AdvertySessionActivated;
}

private void AdvertySessionActivated()
(Adverty.Unit  unit, Adverty.AdUnit.AdConfiguration configuration)
{
    //ADD ACTION ON SESSION ACTIVATION IF NEEDED
}

AdvertyEvents.AdvertySessionActivationFailed

FailedAdvertySessionActivation fires if an Adverty Session fails to activate.

void Start()
{
    Adverty.AdvertyEvents.AdvertySessionActivationFailed += FailedSessionActivation;
}

private void FailedSessionActivation()
(Adverty.Unit  unit, Adverty.AdUnit.AdConfiguration configuration)
{
    //ADD ACTION ON FAILED SESSION ACTIVATION IF NEEDED
}

AdvertyEvents.UnitActivatedEvent

Every ad unit will request an ad when it is initiated and UnitActivatedEvent will execute when a campaign has been delivered and loaded to the ad unit. AdConfiguration includes information about if the campaign is interactable and/or animated.

void Start()
{
    Adverty.AdvertyEvents.UnitActivatedEvent += UnitActivated;
}

private void UnitActivated(Adverty.Unit  unit, Adverty.AdUnit.AdConfiguration configuration)
{
    //ADD ACTION ON UNIT ACTIVATION IF NEEDED
}

Class AdConfiguration
{
    bool Interactable;
    bool Animated;
}

AdvertyEvents.UnitFailedActivationEvent

Every ad unit will request an ad when it is initiated. If no ad is delivered to an ad unit UnitFailedActivationEvent will execute.

void Start()
{
    Adverty.AdvertyEvents.UnitFailedActivationEvent += FailedActivation;
}

private void FailedActivation(Adverty.Unit unit)
{
    //ADD ACTION ON UNIT FAILED ACTIVATION IF NEEDED
}

AdvertyEvents.UnitDeactivatedEvent

Ad units has life cycles and can after a certain time become deactivated and request new campaigns. UnitDeactivatedEvent fires when a ad unit is deactivated.

void Start()
{
    Adverty.AdvertyEvents.UnitDeactivatedEvent += UnitDeactivated;
}

private void UnitDeactivated(Adverty.Unit  unit)
{
    //ADD ACTION ON UNIT DEACTIVATION IF NEEDED
}

AdvertyEvents.ViewedImpression

Callback to understand when an adunit is considered as viewed. This is only called first time a unit is viewed by the user.

void Start()
{
    Adverty.AdvertyEvents.ViewedImpression += UnitViewed;
}

private void UnitViewed(Adverty.Unit  unit)
{
    //ADD ACTION ON UNIT VIEWED IF NEEDED
}

Unit Interaction

The interactable unit is a great possibility for you to utilize rewarded ads. Rewarded ads is a concept when the user is rewarded for fulfilling an interaction with an ad. The reward is up to you to define. It can be a virtual currency, in-game goods for the application or something else. To use this functionality there are three public events to your exposal in AdvertyEvents.

AdvertyEvents. VideoDoneEvent

When a user has watched the entire video ad this event will trigger. The event returns the Unit component of the completed adUnit. Here follows a code snippet showing how to use it.

void Start()
{
	Adverty.AdvertyEvents.VideoDoneEvent += Reward;
}

private void Reward(Adverty.Unit unit)
{
	//GIVE THE REWARD TO THE USER
}

AdvertyEvents. WebViewOpenedEvent

As the video and store landing page will be shown in fullscreen over your application there is an event that triggers when this overlay is opened. This can be used if your application requires for example pausing. Here follows a code snippet showing how to use it.

void Start()
{
	Adverty.AdvertyEvents.WebViewOpenedEvent += Pause;
}

private void Pause()
{
	//PAUSE THE GAME
}

AdvertyEvents. WebViewClosedEvent

Whenever the fullscreen overlay is closed the WebViewClosedEvent triggers. If you have paused the game this is probably when you want to resume it. Here follows a code snippet showing how to use it.

void Start()
{
	Adverty.AdvertyEvents.WebViewClosedEvent += Resume;
}

private void Resume()
{
	//RESUME THE GAME
}

NOTE: If your rewards includes visuals and some in-game event, this should be executed on AdvertyEvents.WebViewClosedEvent. However, the reward should still be given on Unit.onVideoDone. (WebViewClosedEvent can be triggered without VideoDoneEvent being triggered. For example if the user decides to cancel the video before it finished and close the ad overlay)

NOTE 2: These campaigns uses a native overlay for Android/iOS to display the webview. That means it is not possible to test the full flow inside Unity Editor. This requires running on an Android/iOS device.

General advices

Adverty-sdk requires internet to load ads during runtime and there is always a possibility an ad is not delivered. To give the user an as enjoyable experience as possible we suggest the following actions.

Apply your own texture

You can apply your own texture to a unit. This makes it so that if the AdUnit is not receiving an ad your desired texture will be shown. If an ad is delivered your texture will be replaced by the ad. The ratio of the adUnits are 1.2:1, 1:2 or 16:9 for VR and AR and 1.2:1, 1:2 or 3.88:1 for Mobile. Here is how to do this.

void Start()
{
	unit.GetComponent<Renderer>().material.mainTexture = yourTexture;
}

Disable MeshRenderer

You can disable the MeshRenderer on the Unit-prefab. When an ad is delivered the MeshRenderer is activated. This enables the AdUnit not to render in the game until an actual ad is delivered. You can do this either via the inspector or via code.

void Start()
{
	unit.GetComponent<MeshRenderer>().enabled = false;
}
  • iab
  • iab
  • IAB Sweden
  • Jic webs
  • Tag