控制面板集成向导

更新：控制面板提供集成向导，帮助您了解Tapjoy集成步骤。您仍然可以使用入门向导文件作为参考。您可以直接到新app集成向导, 或者您也可以去Tapjoy控制面板，选择您的app，点击上方导航栏的扳手按钮，在下拉菜单中选择“如何集成”。

入门向导

本页介绍了如何在您的 Android 应用程序中集成Tapjoy SDK 11。当您下载我们的SDK时，确保使用我们提供的TapjoyEasyApp example application 样例应用程序。它包含了许多我们api的样例，便于入门集成。您解压压缩文件之后，可以在TapjoyEasyApp目录下找到它。

• 最低支持Android版本为API Level 14/Android 4.0/Ice Cream Sandwich。

更多帮助, 请参考 常见问题 或者联系 技术支持.

控制面板设置

您所需要做的第一件事情就是在 Tapjoy 控制面板 中设置好您的应用程序。登录控制面板账户后，点击左上角的图标，然后从下拉菜单中选择"+ Add App" 。选择平台，添加名称，选择屏幕方向和app使用的虚拟币。

注意：奖励视频内容默认布局是仅横屏。其他内容，如来自积分墙的视频和全屏插页广告将会和屏幕方向一致。

设置虚拟币

请确认您至少设置了一种虚拟货币。 您必须至少设置一种虚拟货币并且在您的应用中启用该虚拟货币，否则将不会有任何 Tapjoy 广告内容出现在您的应用中。您可以参考设置虚拟币向导。

一旦您在控制面板中设置好了您的应用程序以及虚拟货币, 您就可以开始在您的代码中集成SDK了。本文描述的是如何在一款新的 Android 应用中集成 Tapjoy SDK 11。关于如何升级已有的应用中的 Tapjoy 或 5rocks SDK, 请参考这篇迁移指南。

集成的第一步是下载SDK，猛击这里 download the Android SDK 下载。

解压下载好的SDK文件，您会得到如下图所示的一系列目录和文件：

(“TapjoyEasyApp” 目录下包含了一个示例项目，该项目展示了如何集成Tapjoy SDK。当您在您自己的项目中集成Tapjoy SDK 时，您并不需要用到这个示例项目。)

集成安卓SDK到您的Android Studio项目中的Gradle:

添加如下代码到您应用中的build.gradle。您需要把版本号改成Tapjoy SDK的版本号。

repositories {
 maven {
 name "Tapjoy's maven repo"
 url "https://tapjoy.bintray.com/maven"
 }
}

dependencies {
 api 'com.tapjoy:tapjoy-android-sdk:12.3.1@aar'
}

手动方法：

您也可以直接添加jar文件，并把它放入您的gradle编辑中。

1. 拷贝tapjoyconnectlibrary.jar文件到project’s /lib文件夹(如果没有，请先创建)
2. 添加到您项目的build.gradle:

   dependencies {
     compile files('libs/tapjoyconnectlibrary.jar')
   }
   

3. 添加Google-Play-Service库并设置dependencies (点击这里查看来自Google的向导)。

集成Android SDK到其他开发环境中:

1. 添加tapjoyconnectlibrary.jar文件到您的libs文件夹
2. 如果您没有设置Google Play Services，请先设置。点击查看设置Google Play Services。

注意: 如果您在一个已经创建好的app中添加SDK, alt-click 您的项目并且选择 “Properties”。 在左边的面板中选择 “Android”, 添加 “google-play-services_lib” 项目。

添加应用的 Permissions 和 Activities

需要添加下面的 permissions:

• INTERNET
• ACCESS_NETWORK_STATE
• ACCESS_WIFI_STATE (optional)

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

如想使用Tapjoy的全部功能, 添加下面的 activities 到您的AndroidManifest.xml文件中：

<activity
  android:name="com.tapjoy.TJAdUnitActivity"
  android:configChanges="orientation|keyboardHidden|screenSize"
  android:hardwareAccelerated="true"
  android:theme="@android:style/Theme.Translucent.NoTitleBar.Fullscreen" />
<activity
  android:name="com.tapjoy.mraid.view.ActionHandler"
  android:configChanges="orientation|keyboardHidden|screenSize" />
<activity
  android:name="com.tapjoy.mraid.view.Browser"
  android:configChanges="orientation|keyboardHidden|screenSize" />
<activity
  android:name="com.tapjoy.TJContentActivity"
  android:configChanges="orientation|keyboardHidden|screenSize"
  android:theme="@android:style/Theme.Translucent.NoTitleBar"
  android:hardwareAccelerated="true" />

注意：对于旧的SDK版本，点击这里查看向导。

集成Google Play Services，您需要添加如下：

<meta-data
  android:name="com.google.android.gms.version"
  android:value="@integer/google_play_services_version" />

重要: 如果您在使用 Proguard，在您的配置文件中添加如下内容:

-keep class com.tapjoy.** { *; }
-keepattributes JavascriptInterface
-keepattributes *Annotation*
-keep class * extends java.util.ListResourceBundle {
protected Object[][] getContents();
}
-keep public class com.google.android.gms.common.internal.safeparcel.SafeParcelable {
public static final *** NULL;
}
-keepnames @com.google.android.gms.common.annotation.KeepName class *
-keepclassmembernames class * {
@com.google.android.gms.common.annotation.KeepName *;
}
-keepnames class * implements android.os.Parcelable {
public static final ** CREATOR;
}
-keep class com.google.android.gms.ads.identifier.** { *; }
-dontwarn com.tapjoy.**

现在请先编译运行一下您的项目，以确保一切正常。目前还没有在您的程序中添加任何代码，所以当运行时，应该不会有任何错误信息，您的应用的功能也不会有任何的变化。如果在编译运行过程中，您遇到了任何问题，请参考 常见问题 或者联系 技术支持。

接下来我们添加一些Tapjoy相关的code吧!要添加 Tapjoy connect 调用，您需要取得您正在集成的应用的 Tapjoy SDK Key。在Tapjoy控制面板中选择您的应用程序, 点击左下角的 “Setting”按钮:

SDK Key 是一长串数字字母组成的字符串，如下图中显示的：

现在我们可以写入一些代码，在您的主程序文件中引入 Tapjoy SDK:

import com.tapjoy.Tapjoy;

下一步是在代码中添加 Tapjoy connect 语句。正是这条关键语句激活了您应用程序中的Tapjoy SDK。Tapjoy connect 调用非常关键, 因为如果这条语句调用错误的话，其他所有的Tapjoy 功能都不能够正常工作。

在您的应用的主Activity类的onCreate()方法中添加Tapjoy.connect():

示例：

Hashtable<String, Object> connectFlags = new Hashtable<String, Object>();
connectFlags.put(TapjoyConnectFlag.ENABLE_LOGGING, "true");      // remember to turn this off for your production builds!

Tapjoy.connect(getApplicationContext(), tapjoySDKKey, connectFlags, new TJConnectListener() {
			@Override
			public void onConnectSuccess() {
				TapjoyEasyApp.this.onConnectSuccess();
			} 

			@Override
			public void onConnectFailure() {
				TapjoyEasyApp.this.onConnectFail();
			}
		});

完成代码示例请参考SDK中的EasyApp示例。
更多关于 connectFlags 的解释, 请参考 Java SDK Reference。

对于开发者来说，最实用的是ENABLE_LOGGING和USER_ID。设置连接的USER_ID，对于AppLaunch布局获取用户ID很有必要。对于Push2Earn布局，也要在定义布局之前设置好这项。

追踪用户session

在您集成Tapjoy的步骤中，Session 追踪是重要而必不可缺的一部分。就算您对session信息不感兴趣, Tapjoy的其他一些指标和报表都依赖于session信息。按如下步骤启用session信息:
在每一个Activity的onStart 和 onStop中调用相应的 Tapjoy.onActivityStart 和 Tapjoy.onActivityStop。

@Override
protected void onStart() {
  super.onStart();
  Tapjoy.onActivityStart(this);
}

@Override
protected void onStop() {
  Tapjoy.onActivityStop(this);
  super.onStop();
}

追踪用户Session的注意事项:

• 用户的实时活动每隔10分钟都会下降。这是否正常?
• 每隔10分钟，我们都会排除那些在该应用停留了1小时以上的用户。因此这种每隔10分钟的数据周期性的下降是正常的。

• 在集成了session信息之后, 我能得到哪些report?
• 您可以看到活跃用户的报表(DAU/WAU/MAU), 新/回头 用户数, 安装数, session 数, 平均 session 时长, FQ(7/30 day play frequency), 留存(classic & rolling), 潜在/回头 用户数, 并且是实时的。

注意：如果您的app是Android 4.0或者更高的版本，您不必使用半自动api，因为Tapjoy将会通过实施onActivityStart和onActivityStop api来自动追踪会话。如果您计划使用隐式追踪，请注意您app的minSdkVersion版本至少为14，来确保可以准确追踪。

现在请编译并且运行您的应用程序。

在Tapjoy控制面板中，如果您点击左侧的的导航栏中的”Real-time”标签，您应该能够看到您的应用的一些实时的应用数据，您可以多运行几次程序，这样用来展示的数据会更多：

恭喜您! 现在Tapjoy 已经开始在您的应用程序中工作了。

调试模式 & 开发者控制台

调试模式使得您可以看到许多不同的Tapjoy功能的logs(sessions, placements, purchases, custom events, etc. )。 这些信息会出现在Tapjoy开发者控制台中。要使用开发者控制台的话, 在控制面板的右上部分选择 "Tools" 菜单并且选择 "Developer Console"。 主要 调试模式（debug mode） 和 启用logging (enabling logging） 是两个分别独立的设置。

如果您想看到这些信息，在初始化SDK之后并且 调用任何Tapjoy接口之前 添加如下的代码:

Tapjoy.setDebugEnabled(true);

注意: 不要把开启了调试模式的应用发布到App Store上。

开发者控制台只会显示那些发生在它打开的时候的事件。它不会显示那些在它打开之前发生的Tapjoy事件。以下是这些log的例子:

更多信息请参考how to read the developer console。

通过SDK检查连接状态

您已经在运行SDK了，您可以运行代码来使用。在您开始使用Tapjoy SDK的功能之前，需要成功连接到我们的服务器。’connect’调用使用TJConnectListener作为参数。一旦SDK成功连接，TJConnectListener将会显示’onConnectSuccess’。您在尝试获取广告或者追踪数据之前，应该确保SDK已经成功连接。

//Connect call success.
@Override
public void onConnectSuccess() 
{
    //The SDK is now connected.
    //We can start preloading our placements now that we are connected
    TJPlacementListener placementListener = myPlacementListener;
    TJPlacement p = new TJPlacement(this, "MyPlacementName", placementListener);
}

您也可以通过检查Tapjoy.isConnected()来检查SDK的连接状态。

好了，现在Tapjoy已经集成到您的应用中了，让我们看看能用它做些什么。

Placements

Placement 是使用Tapjoy SDK 11向您的用户显示内容时的最重要的概念之一，您需要理解它。placement 是在您的应用中的一个特定的区域，您要在这个区域来向您的用户展示Tapjoy内容。典型的 Placements 包括 AppOpen, WatchVideoForReward, 以及 MainMenu. 所有Tapjoy 内容都会通过应用中设定的 Placements 来展示。 这些内容包括广告内容 (积分墙, 在用户观看后会奖励虚拟币的视频广告, 或者是全屏的互动广告) 或者是一条来您发送给您的用户的自定义信息 (一条您的应用内可购买商品的促销信息, 或者是发布一项新的功能)。 所有如果您要再您的应用中展示积分墙，您并不需要直接调用一条展示积分墙的API。取而代之的是，您可以创建一个Placement,并且在Tapjoy控制面板中将积分墙内容加入到这个Placement中。

当您创建了一个Placement以后，您可以不用修改代码，而是仅仅通过Tapjoy控制面板来改变这个Placement的内容。您可以想象Tapjoy Placement是一块广告牌，而Tapjoy内容则是广告牌上展示的内容。Placement系统的强大之处在于您可以随时根据您的喜好来改变一个Placement的展示内容：当您的应用第一次启东时，这种类型的内容可能是再合适不过的。但当应用投入使用以后，您或许会想要把内容换成别的什么。比如，较之于广告，您可能更想要发布一条关于您所开发的新应用的通告。通过使用Placements，您可以不用重新向App Store提交您的应用从而改变所想要展示的内容。

创建一个Placement仅需要两步：

首先，在Tapjoy控制面板的左边导航栏中点击“Content”，然后点击右上方的”Manage Placements”按钮。再点击右上方的“Create Placement”按钮来创建一个placement

其次，在您的应用中的合适的位置集成Placement代码。

应用中的Placement代码

创建Placement需要使用TJPlacement类。请确保您代码中的Placement名称和控制面板上的完全一致：

// Set current activity. If you are using Tapjoy session tracking or supported minSdkVersion>14,
//	this can be skipped. 
Tapjoy.setActivity(activity);

TJPlacementListener placementListener = this;
TJPlacement p = Tapjoy.getPlacement("APP_LAUNCH", placementListner);

当listener方法已经就位并且placement也已经被初始化了以后，您可以为这个placement添加内容：

if(Tapjoy.isConnected())
	p.requestContent();
else
	Log.d("MyApp", "Tapjoy SDK must finish connecting before requesting content.")

为了最佳用户体验，您应该在用户观看内容之前提前请求。比如，如果placement是您主菜单的一个按钮，您可能想要在应用开始时，Tapjoy连接成功后请求内容。如果您最后才请求内容，用户有可能要等内容加载一段时间。对于广告来说，这会使用户无法和广告互动，从而不能为您盈利。

您需要展示内容时：

if(p.isContentReady()) {
    p.showContent();
}
else {
    //handle situation where there is no content to show, or it has not yet downloaded.
}

您可能需要委托方法来处理不同的placement回应。At a minimum your class will need to extend the TJPlacementListener interface (public class YourMainActivity extends and Activity implements TJPlacementListener). The Tapjoy EasyApp sample app has a complete code example showing how this can be done. The primary methods defined by the TJPlacementListener interface are:

public void onRequestSuccess(TJPlacement placement); // This just means the SDK has made contact with Tapjoy's servers. It does not necessarily mean that any content is available.
public void onRequestFailure(TJPlacement placement, TJError error);
public void onContentReady(TJPlacement placement); //This is called when the content is actually available to display.
public void onContentShow(TJPlacement placement);
public void onContentDismiss(TJPlacement placement);

需要注意的是当一个placement的内容有可能含有视频的时候，您需要将应用的声音调到静音，否则视频的声音和您的应用的声音可能会冲突。

处理Tapjoy Content Action请求

一些Tapjoy内容，比如Reward以及IAP促销，要求您的代码基于内容所传递的参数采取行动。比如，Reward内容要求将事物名称（字符串）以及数量（整数）返回给用户。当然获得Reward以后用户账户的余额仍然是由您的应用来调整的。下列委托方法是在content unit中被调用并且传递适当信息的：

public void onPurchaseRequest(TJPlacement placement, TJActionRequest request, String productId); //onPurchaseRequest called when user clicks the product link in IAP promotion content. Put the code that actually triggers the IAP here.
//
//
public void onRewardRequest(TJPlacement placement, TJActionRequest request, String itemId, int quantity); //called when the content closed in reward content

查看如下文件来学习如何使用特殊内容单元。.Reward Giveaway Content Units. "In App Promotion" Content Units.

默认的Placements

默认的两个布局是在控制后台创建新app时自动生成的，它们的特殊之处在于不需要代码来完成。点击链接查看详情。

推荐的Placements

当您使用了Placements后，您可以不用重新提交您的应用就得以控制Placements展示的内容。因此，我们建议您在集成初始化的时候就创建相当一系列的placements，在所有您能想到的想向用户展示内容的地方都考虑创建一个Placement。以下是我们推荐您在您的代码以及控制面板中可以应用的Placements：

Name	Initializing Code	Recommended Content Type
App Launch	new TJPlacement(context, "App Launch", placementListner);	Announcement, IAP Promotion
App Resume	new TJPlacement(context, "App Resume", placementListner);	Announcement, IAP Promotion
App Close	new TJPlacement(context, "App Close", placementListner);	Offerwall,  Interstitial
Main Menu	new TJPlacement(context, "Main Menu", placementListner);	Announcement, IAP Promotion
Pause	new TJPlacement(context, "Pause", placementListner);	Video,  Interstitial
Stage Open	new TJPlacement(context, "Stage Open", placementListner);	Video,  Interstitial
Stage Complete	new TJPlacement(context, "Stage Complete", placementListner);	Video,  Interstitial
Stage Failed	new TJPlacement(context, "Stage Failed", placementListner);	IAP Promotion
Level Up	new TJPlacement(context, "Level Up", placementListner);	Video,  Interstitial
Store Open	new TJPlacement(context, "Store Open", placementListner);	IAP Promotion
In App Purchase	new TJPlacement(context, "In App Purchase", placementListner);	Reward Giveaway
Abandon In App Purchase	new TJPlacement(context, "Abandon In App Purchase", placementListner);	IAP Promotion, Offerwall
Virtual Good Purchased	new TJPlacement(context, "Virtual Good Purchased", placementListner);	Reward Giveaway, Announcement
Sign Up Complete	new TJPlacement(context, "Sign Up Complete", placementListner);	Reward Giveaway
User High Score	new TJPlacement(context, "User High Score", placementListner);	Reward Giveaway
Out of Goods	new TJPlacement(context, "Out of Goods", placementListner);	IAP Promotion
Out of Energy	new TJPlacement(context, "Out of Energy", placementListner);	IAP Promotion
Insufficient Currency	new TJPlacement(context, "Insufficient Currency", placementListner);	Offerwall
Finished Tutorial	new TJPlacement(context, "Finished Tutorial", placementListner);	Reward Giveaway, Announcement

在Placements中添加内容

当您已经在您的应用以及控制面板中创建了placement以后，您可以开始向这些
您可以创建6种不同的内容：

1. In App 产品促销：这是为您游戏中的IAP产品所设立的广告
2. Display Ad(显示广告)：这是用户不能自行启动的一种广告，这种内容实际上会”暂停“您的应用（在主菜单中，完成一个等级后，等等）
3. Offerwall(积分墙)：这是用户可以完成的一系列含有不同额度虚拟币奖励的广告。
4. Auto Play Video(自动播放视频)：用户看完一个视频后会获得小额的虚拟币奖励。这是用户可以自行启动的placements中的内容（比如，点击”观看视频赢取虚拟币“按钮）
5. Announcement(通告)：向您的用户展示的一条消息。这种内容可以含有一个”点击进入“的按钮将用户重定向到一个特定的网址。
6. Reward(奖励)：和通告类似，但在用户关闭内容的同时会回调您代码中的一个链接以此奖励用户特定数额的某种项目。

创建布局和内容的视频教学

创建插页广告视频教学(曾是Display Ad，包括Placement创建)：

创建通知视频教学（包括Placement创建）：

创建一个Content Unit（内容单元）:

1. 点击做菜单栏的”Content”
2. 点击控制面板右上角的蓝色的”Create Content”按钮
3. 选择您想要的content种类
4. 填写表单，设置用户分类，placement，时间表以及虚拟币。如果您想要内容得以展示，请将其添加到应用中所使用的placements中

Content创建中的注意事项：

• 我可以在我的Android和iOS应用中使用同一个内容吗？
  • 不行。内容每次只能应用在一个平台上。请在您创建内容前确认您想要使用的平台，因为一旦内容创建了平台就不能换了。

检查是否有内容

当您请求TJPLacement时，您会传递TJPLacementListener对象，您的TJPlacementListener会回调"onRequestSuccess"。SDK成功向我们的服务器请求内容后会触发onRequestSuccess。您可以通过调用isContentAvailable功能检查是否有内容:

@Override
public void onRequestSuccess(TJPlacement tjPlacement)
{
	if(tjPlacement.isContentAvailable())
	{
		//There is an ad unit available
	}
	else
		//Fall-through
}

注意isContentAvailable表示有广告，但不意味着下载已完成。一旦广告完成加载，就会触发TJPlacementListener的 onContentReady 功能。您也可以调用isContentReady 检查是否加载完成。加载完成之后，您可以通过调用showContent功能在任何时间展示广告。

public void onContentReady(TJPlacement tjPlacement) 
{
	if(tjPlacement.isContentReady()) 
	{
		// We can uncomment the following line to show the ad as soon as it finishes loading, 
		// or call showContent at a later point once we're ready to display the ad.
	    //tjPlacement.showContent();
	}
}

奖励用户与广告互动

为了奖励您的用户与广告互动，您必须创建虚拟币系统。这包括党用户完成广告任务后您如何收到通知，以及用户会得到多少虚拟币等。Tapjoy有两种您可以选择的虚拟币系统。

1. 货币管理服务：服务器追踪用户虚拟币余额，Tapjoy SDK可以提醒应用程序余额的改变。
2. Self-managed currency,：您可以使用您自己的服务器追踪虚拟币余额，Tapjoy通过您在后台设置的URL通知您的服务器完成广告的奖励。

想要了解更多信息，请查看virtual currency documentation。

用户属性

通过设置不同的用户属性,比如等级，同类别用户，以及ID，您可以通过Tapjoy控制面板自动获取强大的分析数据。比如，当您设定了用户等级，您都可以通过用户在游戏等级中的表现来得知整个游戏中不同等级的用户分布。

Tapjoy.setUserLevel(1); // Set the user level to 1

这可以让您在控制面板的”Game Trend”区域中看见如下的图表：

用户ID

您可以设置用户ID，大部分Tapjoy SDK 11集成不需要这一步骤，Tapjoy SDK 11会为您自动生成用户ID，但是会有如下情况需要您设置您自己的用户ID。

1. 如果您使用self-managed currency，您必须指定用户ID。这是因为当Tapjoy服务器给您的服务器发送用户赚取虚拟币的消息时，它就可以知道哪个用户接收虚拟币。

2. 如果您使用managed currency，并且想让您的用户在多台设备上都保有虚拟币余额，您必须指定用户ID，并确保用户在所有设备上的用户ID都一样。

3. 如果您使用server-to–server对接（在使用之前请先和Tapjoy客户经理沟通） ，您需要确保设备上app的用户ID和您服务器上的用户ID一致。

如果不能正确的设置用户ID（或应该由Tapjoy SDK为您设置）将会导致用户不能通过Tapjoy获得奖励，或者使用户的余额不正常地增长或减少。

您可以使用如下代码设置用户ID:

Tapjoy.setUserID("your-user-id");

用户类别组变量:

您可以设置5个不同的用户类别组，这将使您能够根据不同的用户组来设置不同的内容，或者在控制面板的”side-by-side”视图中比较不同用户组的行为表现：

Tapjoy.setUserCohortVariable(1, "Warrior");
Tapjoy.setUserCohortVariable(1, "Enchanter");

用户属性注意事项：

• 我可以设置多少个用户类别组？
  • 5个
• 不论用户何时开始游戏/应用时，我都要加入setUserLevel吗？
  • 不。尽在用户等级初始化或者改变时才调用这个变量。
• 除了用户等级，还有其他我可以在控开关至面板使用的用户变量吗？
  • 你可以发送用户ID，朋友数量，以及自定义用户类别组。
• 怎样才能重置等级信息？
  • 发送一个负值而不是等级数. [Tapjoy setUserLevel:-1];

商城组别

商城组别可以让您追踪到您的应用是从哪个商城里下载的。

在AndroidManifest.xml. String里如下标识可以被赋值为应用商城，如“Google”或“Amazon”。

<manifest>
  <application>
  ...
    <meta-data android:name="com.tapjoy.appstore" android:value="Google"/>
  ...
  </application>
</manifest>

追踪购买

重要提示：用户有必要通过Tapjoy追踪呼叫（SDK 11.2.0及以上版本）来引入IAP购买收据，或者使用Google的收据验证系统验证（或一切适合您使用的）之后再发给Tapjoy。如果您不这么做，几乎可以确定的事您的指标和细分统计将被欺诈交易搅乱。而这将破坏很多Tapjoy提供的功能，包括预期价值走向图和高消费用户定向投放功能。

通过消费行为细分用户事Tapjoy SDK 11版本最强大的功能之一。例如，您的广告主要是想显示给您的非消费用户，但是事实上却把广告投向了您的高端付费用户。要使用这项功能，必须让Tapjoy了解您的用户的消费活动。您只需要在代码中使用使用[Tapjoy trackPurchase]， 下面是一个购买道具“剑”的而产生的0.99美元交易实例：

为了让购买跟踪的收据验证在Android上正常工作，你必须输入你的应用程序的许可证密钥到应用程序设置 – >分析 – >收据验证

您可以从这里获取您的应用许可 Licensing section of the Google Services Documentation..

以下调用用于跟踪购买收据验证：

Tapjoy.trackPurchase(skuDetails, purchaseData, dataSignature, campaignID);

参数说明：
1. skuDetails – 用JSON对象格式的字符串包含产品项目的详细信息（遵循谷歌规范）
2. purchaseData- JSON格式的字符串，其中包含有关采购订单的详细信息。它是由你的操作系统进行购买后返回。使用空值将不使用验证。
3. dataSignature – 字符串包含开发人员用自己的私钥签署了购买数据的签名。它是由你的操作系统进行购买后返回。使用空值将不使用验证。
4. campaignId – 发起购买活动的campaign ID。这可以为空，如果你不希望跟踪哪些活动发起此次收购。

以下是没有使用Tapjoy收据验证系统的例子。当且仅当你已经在之前完成收货验证才可以进行此种调用。

@Override
public void onActivityResult(int requestCode, int resultCode, Intent data) {
  Log.d(TAG, "onActivity Result Code : " + resultCode);

  if (requestCode == REQUEST_CODE_PURCHASE) {
    String purchaseData = data.getStringExtra("INAPP_PURCHASE_DATA");
    String dataSignature = data.getStringExtra("INAPP_DATA_SIGNATURE");

    // get receipt here.
    if (resultCode == Activity.RESULT_OK) {
      try {
        JSONObject purchaseDataJson = new JSONObject(purchaseData);
        String productId = purchaseDataJson.getString("productId");

        // getSkuDetails
        ArrayList skuList = new ArrayList<> ();
        skuList.add(productId);
        Bundle querySkus = new Bundle();
        querySkus.putStringArrayList("ITEM_ID_LIST", skuList);
        Bundle skuDetails = mService.getSkuDetails(3, getActivity().getPackageName(), "inapp", querySkus);
        ArrayList responseList = skuDetails.getStringArrayList("DETAILS_LIST");

        // Remove empty purchase data and signatures
        if(purchaseData.isEmpty() || purchaseData == null)
	purchaseData = "Empty_Purchase_Data";

        if(dataSignature.isEmpty() || dataSignature == null)
	dataSignature = "Empty_Data_Signature"
	
        //Track the purchase
        Tapjoy.trackPurchase(responseList.get(0), purchaseData, dataSignature, null);
                //The fourth parameter is a string that lets you specify a campaign ID should you choose to do so.

      } catch (JSONException e) {
        e.printStackTrace();
      } catch (NullPointerException e){
        e.printStackTrace();
      } catch (RemoteException e) {
        e.printStackTrace();
      }
    }
  }
}

代码遵循 ISO 4217 standard.

当您使用了追踪购买以后，您就能够在控制面板的”IAP Revenue”中看到如下的图标了：

Referrer

您可以使用Tapjoy来追踪是谁引导您的用户来安装这个安卓版的应用的
在AndroidManifest.xml中如下所示在标签中注册Tapjoy Install Referrer Receiver

...
<manifest ...>
  ...
  <application ...>
  ...
    <receiver
      android:name="com.tapjoy.InstallReferrerReceiver"
      android:exported="true">
      <intent-filter>
        <action android:name="com.android.vending.INSTALL_REFERRER"/>
      </intent-filter>
    </receiver>
  ...
  </application>
  ...
</manifest>

问答

• 我可以使用多个Install Referrer Receivers吗？
  • 是的，请参考这篇文章.

推送通知

注意：从2018年4月10日开始，Google正式弃用GCM。GCM服务器和客户端API已经弃用并将于2019年4月11日删除。将GCM应用程序迁移到Firebase云消息传递（FCM），后者继承了可靠且可扩展的GCM基础架构以及许多新功能。 请参阅迁移指南以了解更多信息。

FCM 配置指南

在Firebase Console 添加应用工程并下载配置文件“google-services.json”，同时在LTV dashboard更新API密钥和Sender ID。

关于如何得到Sender ID 和API 密钥，请参考这里。

在您的APP中添加Firebase SDK。

将已下载的“google-services.json”文件添加到您工程的根目录。

在 <project level>/build.gradle中添加：

classpath 'com.google.gms:google-services:4.0.1’

在<app level>/build.gradle中添加：

Maven { 
  url ‘https://maven.google.com’ 
  name ‘Google’ 
}

compile “com.google.firebase:firebase-messaging:17.0.0”
compile “com.google.firebase:firebase-ads:15.0.1”

在build.gradle的底部添加：

  apply plugin: 'com.google.gms.google-services' 

注意： Firebase云消息要求Android API 14及以上版本。对于API 14以下版本，请使用firebase-messaging 10.2.6版本并且firebase-ads库不再需要。

为了集成Tapjoy push notification API，请参考以下步骤：

在您App的工程中创建两个类分别扩展FirebaseMessagingService 和 FirebaseInstanceIdService

在这两个类中，分别调用Tapjoy push notification APIs

Tapjoy.setReceiveRemoteNotification(remoteMessage.getData());

和

Tapjoy.setDeviceToken(deviceToken);

如下所示或查看EasyApp源代码：

public class FCMMessageService extends FirebaseMessagingService {

@Override
public void onMessageReceived(RemoteMessage remoteMessage) {
   Tapjoy.setReceiveRemoteNotification(remoteMessage.getData());
}

public class FCMTokenService extends FirebaseInstanceIdService {

@Override
public void onTokenRefresh() {
 // Get updated InstanceID token. 
 String deviceToken = FirebaseInstanceId.getInstance().getToken();
 Tapjoy.setDeviceToken(deviceToken);
}

在您应用的 AndroidManifest.xml添加如下：

<service android:name="<your_FirebaseInstanceIdService_name>">
  <intent-filter>
    <action android:name="com.google.firebase.INSTANCE_ID_EVENT" />
  </intent-filter>
</service>
<service android:name="<your_FirebaseMessagingService_name">
 <intent-filter>
   <action android:name="com.google.firebase.MESSAGING_EVENT"/>
 </intent-filter>
</service>

GCM 配置指南

设置GCM Sender ID

Tapjoy.setGCMSender("YOUR-SENDER-ID"); // OR "YOUR-SENDER-ID-1, YOUR-SENDER-ID-2"

GCM要求额外的权限设置，将下列代码添加到AndroidManifest.xml文件中

<manifest ...>
  ...
  <uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" />
  <uses-permission android:name="android.permission.GET_ACCOUNTS"/>

  <permission
    android:name="YOUR.PACKAGE.NAME.HERE.permission.C2D_MESSAGE"
    android:protectionLevel="signature"/>
  <uses-permission android:name="YOUR.PACKAGE.NAME.HERE.permission.C2D_MESSAGE"/>
  ...
</manifest>

如果你的android:minSdkVersion 设置是 API 15 或者更早版本，你需要添加GET_ACCOUNTS权限来使用推送功能。 API level 16以及以上版本的设置无需做这一步。

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

添加Receiver链接到GCM。

<manifest ...>
  ...
  <application ...>
    ...

    <receiver
        android:name="com.tapjoy.GCMReceiver"
        android:permission="com.google.android.c2dm.permission.SEND">
      <intent-filter>
        <action android:name="com.google.android.c2dm.intent.REGISTRATION"/>
        <action android:name="com.google.android.c2dm.intent.RECEIVE"/>
        <action android:name="com.google.android.gcm.intent.RETRY"/>
        <category android:name="YOUR.PACKAGE.NAME.HERE"/>
      </intent-filter>
    </receiver>
    <receiver android:name="com.tapjoy.TapjoyReceiver" />

    ...
  </application>
  ...
</manifest>

在发送push notification前，你需要在Tapjoy控制面板中设置server key。请点击控制面板左下方的”Setting”然后在左菜单栏中选择”Push”来配置您的key。

Sender ID和API Key可以在Google API Console找到。

Push注意事项

• Can I use another push provider or my own push server simultaneously with Tapjoy?
  • 我可以在使用Tapjoy的同时选择另一个push提供商或者我自己的push服务吗？
    • 是的，可以。
  • 我的push认证快要到期了
    • 请在到期前替换一个新的认证。

发送自定义负载

当用Tapjoy发送推送通知时，您可以发送自定义负载（可以进入控制面板但用户不可见的字符串）。自定义负载可以为任意字符串，您的app可以用您设定的反应方式解析字符串。常见应用包括奖励用户反馈通知消息，在应用中通过自定义URL给用户发送特定位置。想要了解如何在您的app 上阅读自定义推送负载，请点击自定义负载文件。

自定义通知按钮

当您发送通知时应用按钮会通过Tapjoy控制面板被设置成默认通知按钮（GCM消息）。您可以如下通过在应用项目的AndroidManifest.xml文件里<application>标志中指定resource：

//notification bar small icon. 
<meta-data android:name="com.tapjoy.notification.icon" android:resource="@drawable/{id}"/>  

//notification panel large icon. (above 11.6.0)  
<meta-data android:name="com.tapjoy.notification.icon.large" android:resource="@drawable/{id}"/>  

//The icon which is using partial alpha value below android 5.0 (above 11.6.0)
<meta-data android:name="com.tapjoy.notification.icon.compat" android:resource="@drawable/{id}"/>

Push Opt out API for Android SDK 11.1+

您可以通过使用API筛选出不想接受推送通知的用户。使用之前您应该先通过调用Tapjoy.connect连接Tapjoy SDK。

// To get the current status
boolean Tapjoy.isPushNotificationDisabled();

// To set/unset push notification disabled
void Tapjoy.setPushNotificationDisabled(boolean);

我们建议在您的app设置页面添加触发开关或检查框界面。

C++支持

Tapjoy在使用Android NDK和C++的开发平台上提供C++ API, 比如Cocos2d-x。

Tapjoy Android SDK 提供的C++ API和Tapjoy iOS SDK提供的 C++ API兼容。

NDK模型

Tapjoy SDK里包含提供C++头文件和库的NDK模型。请添加Tapjoy NDK Modules路径，如NDK_MODULE_PATH。

ndk-build NDK_MODULE_PATH=../../TapjoySDK_Android/Library/modules

Cocos2d-x

添加NDK_MODULE_PATH到proj.android/build_native.sh，用冒号（：）分隔:

 # proj.android/build_native.sh
...
if [[ "$buildexternalsfromsource" ]]; then
    echo "Building external dependencies from source"
    "$NDK_ROOT"/ndk-build -C "$APP_ANDROID_ROOT" $* \
       "NDK_MODULE_PATH=${COCOS2DX_ROOT}:${COCOS2DX_ROOT}/cocos2dx/platform/third_party/android/source:../../TapjoySDK_Android/Library/modules"
else
    echo "Using prebuilt externals"
    "$NDK_ROOT"/ndk-build -C "$APP_ANDROID_ROOT" $* \
       "NDK_MODULE_PATH=${COCOS2DX_ROOT}:${COCOS2DX_ROOT}/cocos2dx/platform/third_party/android/prebuilt:../../TapjoySDK_Android/Library/modules"
fi

使用如下模型之一：

静态库模型

把您的应用库连接到静态库模型。

添加fiverocks_static模型:

从app项目中, 添加 tapjoy_static模型到构建Tapjoy API集成源代码的Android.mk文件中。

```make
 ...
 include $(CLEAR_VARS)
 ...
 LOCAL_STATIC_LIBRARIES := tapjoy_static
 ...
 include $(BUILD_SHARED_LIBRARY)
 ...
 $(call import-module,tapjoy)
 ...
```

提供JavaVM:

tapjoy_static模型需要JavaVM对象。找到JNI_OnLoad的功能定义并添加到Tapjoy::setJavaVM 中。

 ...
  #include "TapjoyCpp.h" // Tapjoy C++ API
 ...
 jint JNI_OnLoad(JavaVM *vm, void *reserved) {
     ...
     JniHelper::setJavaVM(vm);
     tapjoy::Tapjoy::setJavaVM(vm);
     ...
 }
 ...

共享库模型

您也可以使用共享库模型。这不需要JavaVM。

添加tapjoy_shared模型

从app项目中，添加tapjoy_shared模型到构建Tapjoy API集成源代码的 Android.mk文件中：

```make
...
include $(CLEAR_VARS)
...
LOCAL_SHARED_LIBRARIES := tapjoy_shared
...
include $(BUILD_SHARED_LIBRARY)
...
$(call import-module,tapjoy)
...
```

解决共享库模型的依赖问题：
在加载使用Tapjoy库的应用库之前，调用Tapjoy.loadSharedLibrary():

```java
...
import com.tapjoy.Tapjoy;
...
  static {
    Tapjoy.loadSharedLibrary();
    System.loadLibrary("YourAppLibrary");
  }
```

C++ API

使用TapjoyCpp.h头文件:

...
 #include "Tapjoy/TapjoyCpp.h" // Tapjoy C++ API
...
using namespace tapjoy;
...
  Tapjoy::trackEvent("some event");
...

Push Opt out C++ API for Android SDK 11.1+

您可以通过使用API筛选出不想接受推送通知的用户。使用之前您应该先通过调用Tapjoy.connect连接Tapjoy SDK。

// To get the current status
bool Tapjoy::isPushNotificationDisabled()

// To set/unset push notification disabled
void Tapjoy::setPushNotificationDisabled(bool)

我们建议在您的app设置页面添加触发开关或检查框界面。