chinese unity integration guide - unity-cn/unityads-help-cn GitHub Wiki

/*
Title: Integration Guide for Unity
Description: A guide to integrating Unity Ads in Unity
Sort: 15
*/

大纲

快速启动

在深入很细之前, 我们先从简单的集成例子开始. Before going into too much detail, let's start off with a simple integration example. Unity Ads 集成一般需要以下3步:

  1. 初始化.
  2. 检查广告准备好了.
  3. 展示广告.

下边的例子在 Start 方法里初始化了 Unity Ads, Ready之后显示了 默认的 (default)广告位 ( placement ). 如果Unity Ads 是从 Services window 开启来集成的, 那么Unity Ads会自动初始化. 其他的地方都是一样的.

C# Example – ShowAdOnStart.cs

using UnityEngine;
using System.Collections;
using UnityEngine.Advertisements; // Using the Unity Ads namespace.

public class ShowAdOnStart : MonoBehaviour
{
	#if !UNITY_ADS // If the Ads service is not enabled...
	public string gameId; // Set this value from the inspector.
	public bool enableTestMode = true;
	#endif

	IEnumerator Start ()
	{
		#if !UNITY_ADS // If the Ads service is not enabled...
		if (Advertisement.isSupported) { // If runtime platform is supported...
			Advertisement.Initialize(gameId, enableTestMode); // ...initialize.
		}
		#endif

		// Wait until Unity Ads is initialized,
		//  and the default ad placement is ready.
		while (!Advertisement.isInitialized || !Advertisement.IsReady()) {
			yield return new WaitForSeconds(0.5f);
		}

		// Show the default ad placement.
		Advertisement.Show();
	}
}

JavaScript Example – ShowAdOnStart.js

#pragma strict
import UnityEngine.Advertisements; // Import the Unity Ads namespace.

#if !UNITY_ADS // If the Ads service is not enabled...
public var gameId : String; // Set this value from the inspector.
public var enableTestMode : boolean = true;
#endif

function Start () : IEnumerator
{
	#if !UNITY_ADS // If the Ads service is not enabled...
	if (Advertisement.isSupported) { // If runtime platform is supported...
		Advertisement.Initialize(gameId, enableTestMode); // ...initialize.
	}
	#endif

	// Wait until Unity Ads is initialized,
	//  and the default ad placement is ready.
	while (!Advertisement.isInitialized || !Advertisement.IsReady()) {
		yield WaitForSeconds(0.5);
	}

	// Show the default ad placement.
	Advertisement.Show();
}

接下来我们细致的看一下集成步骤 Unity Ads.

设置和初始化

有2种方式可以集成Unity Ads:

自从Unity 5.2开始, Unity Ads 的 API 已经作为引擎的一部分了. 这样最大的好处是大大的减少了配置和初始化的流程, 让开发者启动的更快.

但是如果不希望使用Services面板, 开发者仍然可以使用Unity Asset Package, 从4.3到最新版全都可以使用这种方式.

⇧ Back to top

使用服务面板 Services Window

这一节中讲述了在Unity 5.2及之后的版本中, 如何使用Services面板配置和开启Unity Ads.

注意: 在开启了Service的时候, 引擎内置的Unity Ads会和导入的资源包冲突.

如果开发者之前已经使用资源包的方式集成了Unity Ads, 那么在开启Service之前, 需要先删掉资源包导进来的所有文件.

资源包导进来的文件在以下几个地方:

  • Plugins/Android/unityads
  • Plugins/iOS/UnityAds.bundle
  • Plugins/iOS/UnityAds.framework
  • Plugins/iOS/UnityAdsUnityWrapper.h
  • Plugins/iOS/UnityAdsUnityWrapper.mm
  • StandardAssets/Editor/UnityAds
  • StandardAssets/UnityAds

还有一个简单的方法是使用 Package Uninstaller, 截止到最后更新文档的时候, 它还是免费的.

下面开始介绍如何开启Unity Ads Service啦.

Step 1: 设置 Platform 到iOS或者Android以保证广告功能可以正常测试.

  1. 从Menu里选择 File > Build Settings... .
  2. 平台列表(Platform) 里选择iOS或者Android.
  3. 选择 Switch Platform.

Step 2: 从 Services 面板开启Unity Ads.

  1. 选择 Window > Services 开启 Services 面板.
  2. 选择 Ads service 进行设置.
  3. 点击开关来开启 Ads.
  4. 选择这是否是一个特别为13岁一下儿童设计的游戏(通常都不是).
  5. 选择 Save Changes 来完成设置.

COPPA 是美国特有的设置, 并且会严重影响开发者的收入. 一般没有明确的确定自己是COPPA的, 那么并不需要选择它.

如果使用Services面板开启Unity Ads, 那么Unity会为开发者执行Unity Ads的初始化, 所以就不需要手工调用initialize的api了. 并且可以在Advanced下边找到Game ID.

更多细节可以参考Unity引擎文档中的Unity Ads章节. 关于如何显示广告位, 可跳到 Showing an Ad Placement 或者 Using Test Mode.

如何关掉自动初始化(initialization)?

需要注意的是, 大多数时候你需要尽早的初始化Unity Ads. 在网络好的环境下, 一两分钟就可以了. 但如果您使用多家SDK的话, 可能就需要更早了.

在Editor目录下创建一个名为 UnityAdsBuildProcessor 的C#脚本, 并赋予如下代码:

using UnityEditor;
using UnityEditor.Callbacks;
using UnityEditor.Advertisements;

public class UnityAdsBuildProcessor : Editor
{
	[PostProcessScene]
	public static void OnPostprocessScene ()
	{
		AdvertisementSettings.enabled = true;
		AdvertisementSettings.initializeOnStartup = false;
	}
}

⇧ Back to top

使用Unity Ads资源包 ( Asset Package )

这一节中讲述了在Unity 4.3开始的版本中, 如何使用资源包来配置和初始化 Unity Ads

注意: 如果想要使用资源包的话, Services面板中的Unity Ads必须保证是关闭的.

Step 1: 将平台设置为iOS或者Android.

  1. 从Menu中选择 File > Build Settings... .
  2. Platform 中选择iOS或者Android.
  3. 选择 Switch Platform.

Step 2: 下载并导入 Unity Ads 资源包 ( asset package ).

Step 3: 创建一个名 UnityAdsExample 的 GameObject.

  1. 从Menu中选择 GameObject > Create Empty .
  2. 在 Hierarchy 窗口中找到 GameObject.
  3. 右键选择这个 GameObject 选择 Rename 将它重命名为 UnityAdsExample.

Step 4: 创建一个名为 UnityAdsExample 的C#脚本.

  1. 从Menu选择 Assets > Create > C# Script 创建名为 UnityAdsExample 的脚本.
  2. 打开脚本赋予如下代码:

C# Example – UnityAdsExample.cs

using UnityEngine;
using System.Collections;
using UnityEngine.Advertisements; // Declare the Unity Ads namespace.

public class UnityAdsExample : MonoBehaviour
{
	// Define gameId as a public field
	//  so it can be set from the Inspector.
	public string gameId;

	void Start ()
	{
		if (Advertisement.isSupported) { // If the platform is supported,
			Advertisement.Initialize(gameId); // initialize Unity Ads.
		}
	}
}

Step 5: 把脚本加到 UnityAdsExample GameObject 上.

  1. 从Hierarchy窗口选择 UnityAdsExample GameObject.
  2. 从Menu选择 Component > Scripts > Unity Ads Example.

Step 6: 在 Inspector 窗口中设置 Game ID.

如果您不知道Game ID, 可以在 Unity Ads dashboard 的 platforms 列表里找到.

优化这个例子 UnityAdsExample

下面这段代码针对之前的做了一点点优化:

  • 同时支持 iOS 和 Android 的Game ID.
  • 一个 Test Mode 开关选项.

C# Example – UnityAdsExample.cs

using UnityEngine;
using System.Collections;
using UnityEngine.Advertisements;

public class UnityAdsExample : MonoBehaviour
{
	// Serialize private fields
	// instead of making them public.
	[SerializeField] string iosGameId;
	[SerializeField] string androidGameId;
	[SerializeField] bool enableTestMode;

	void Start ()
	{
		string gameId = null;

		#if UNITY_IOS // If build platform is set to iOS...
		gameId = iosGameId;
		#elif UNITY_ANDROID // Else if build platform is set to Android...
		gameId = androidGameId;
		#endif

		if (string.IsNullOrEmpty(gameId)) { // Make sure the Game ID is set.
			Debug.LogError("Failed to initialize Unity Ads. Game ID is null or empty.");
		} else if (!Advertisement.isSupported) {
			Debug.LogWarning("Unable to initialize Unity Ads. Platform not supported.");
		} else if (Advertisement.isInitialized) {
			Debug.Log("Unity Ads is already initialized.");
		} else {
			Debug.Log(string.Format("Initialize Unity Ads using Game ID {0} with Test Mode {1}.",
				gameId, enableTestMode ? "enabled" : "disabled"));
			Advertisement.Initialize(gameId, enableTestMode);
		}
	}
}

⇧ Back to top

使用测试模式 ( Test Mode )

我们强烈建议在开发时候使用测试模式( Test Mode ). 在开启测试模式的情况下, 开发者只能看到测试广告, 这样不会受到每天25个广告的限制.

请注意, 根据 Unity Ads Terms of Service agreement 我们不允许从自己的游戏里产生impression或者点击量. 如果通过自己的游戏产生了impression或者点击的话, 您可能会有被认作是有欺诈行为开发者或玩家. 所以从这个角度, 我们也非常建议在开发和测试的时候开启测试模式.

如果您使用Unity 5.2并且在使用Services面板, 俺么测试模式是默认开启的. 您可以在Services面板中的Settings选项里进行开关.

在使用Advertisement.Initialize进行初始化的时候, 也可以通过传入一个布尔参数来在api级别进行设置 .

在准备发布游戏的时候, 测试模式应该关掉. 开发者既可以在发布前关掉, 也可以在发布后从Unity Ads dashboard 强制关掉. 强制开关在每个游戏的 Settings 里.

⇧ Back to top

如何展示广告位 ( Ad Placement )

这一节讲解了如何展示一个简单的广告位.

创建一个名为 UnityAdsButton 的脚本, 把它放到一个新建的 GameObject 并赋予如下脚本代码:

C# Example – UnityAdsButton.cs

using UnityEngine;
using System.Collections;
using UnityEngine.Advertisements;

public class UnityAdsButton : MonoBehaviour
{
	void OnGUI ()
	{
		Rect buttonRect = new Rect (10, 10, 150, 50);
		string buttonText = Advertisement.IsReady () ? "Show Ad" : "Waiting...";

		if (GUI.Button (buttonRect, buttonText)) {
			Advertisement.Show ();
		}
	}
}

⇧ Back to top

展示奖励式广告位 ( Ad Placement )

这一节讲解了如何添加展示一个奖励式视频广告.

创建一个名为 UnityAdsRewardedButton 的脚本, 把它放到一个新建的 GameObject 并赋予如下代码:

C# Example – UnityAdsRewardedButton.cs

using UnityEngine;
using System.Collections;
using UnityEngine.Advertisements;

public class UnityAdsRewardedButton : MonoBehaviour
{
	public string zoneId;
	public int rewardQty = 250;

	void OnGUI ()
	{
		if (string.IsNullOrEmpty (zoneId)) zoneId = null;

		Rect buttonRect = new Rect (10, 10, 150, 50);
		string buttonText = Advertisement.IsReady (zoneId) ? "Show Ad" : "Waiting...";

		ShowOptions options = new ShowOptions();
		options.resultCallback = HandleShowResult;

		if (GUI.Button (buttonRect, buttonText)) {
			Advertisement.Show (zoneId, options);
		}
	}

	private void HandleShowResult (ShowResult result)
	{
		switch (result)
		{
		case ShowResult.Finished:
			Debug.Log ("Video completed. User rewarded " + rewardQty + " credits.");
			break;
		case ShowResult.Skipped:
			Debug.LogWarning ("Video was skipped.");
			break;
		case ShowResult.Failed:
			Debug.LogError ("Video failed to show.");
			break;
		}
	}
}

⇧ Back to top

API 文档

⇧ Back to top

其他资源

例子, 支持和其他信息可查看 Resources 页面

⇧ Back to top

⚠️ **GitHub.com Fallback** ⚠️