跳到主要内容

适用于 Unity 的 Install Referrer SDK（版本 10.3.0）

SDK Install referrer 是一款用于广告和分析系统的归因工具。 它允许您跟踪通过广告链接从 RuStore 下载并安装您的应用程序的数量。

RuStore 接受如下格式的链接：https://www.rustore.ru/catalog/app/com.packagename.yourapp?referrerId=<referrer>。

当用户点击广告链接并开始安装应用程序时，RuStore 会保存该链接中的 referrer 值。 SDK 会请求 RuStore 获取 referrer 值，并将其通过 InstallReferrer 参数传递给您的应用程序。 这样，应用程序就能获得关于通过特定广告链接完成安装的信息。

在 RuStore 将 referrer 值传递给 SDK 后，该值将从 RuStore 中删除。 即使 SDK 没有请求 referrer，该值在 RuStore 中也仅存储 10 天，之后将被删除。

连接到项目​

请从发布页面下载以下包以进行连接：

  • ru.rustore.core-version.tgz
  • ru.rustore.installreferrer-version.tgz

通过 Package Manager 将包导入到项目中 (Window → Package Manager → + → Add package from tarball...)。

提示

如果您使用的是 macOS 操作系统，请更改归档实用程序的设置。 在 Archive Utility 设置中，取消勾选“尽可能继续解压 (Keep expanding if possible)”。 否则，项目存档将无法正确下载。

为了正确处理 SDK 依赖项，请执行以下设置。

  1. 打开项目设置：Edit → Project Settings → Player → Android Settings。

  2. 在 Publishing Settings 部分，启用以下设置：

    • Custom Main Manifest。
    • Custom Main Gradle Template。
    • Custom Gradle Properties Template。

  3. 在 Other Settings 部分，配置：

    • package name。
    • Minimum API Level = 24。
    • Target API Level = 34。

解决依赖关系​

Android 构建的依赖项将通过 External Dependency Manager 工具自动连接。

要自动解析依赖项，请使用以下命令：Assets → External Dependency Manager → Android Resolver → Force Resolve。 每次添加新版本的插件或重新创建 Assets / Plugins / Android / mainTemplate.gradle 和 Assets / Plugins / Android / settingsTemplate.gradle 文件时，都应执行此操作。

  • 通过 *.unitypackage 安装 RuStore 插件时，无需单独安装 External Dependency Manager。

  • 通过 Package Manager 安装 RuStore 插件时，请执行以下操作：

    • 在软件包管理器窗口中打开 RuStore Core 插件选项卡：Window → Package Manager → Packages RuStore → RuStore Core.
    • 切换到 Samples 选项卡。
    • 导入 External Dependency Manager 示例。

  • 您也可以从 GitHub 上的开发者仓库获取最新版本的 External Dependency Manager：

    • 打开软件包管理器窗口：Window → Package Manager → + → Add package from git URL...。
    • 使用链接 https://github.com/googlesamples/unity-jar-resolver.git?path=/upm 来连接该包。
    • 为了解决 "Google.IOSResolver.dll will not be loaded" 错误，请为您的 Unity 版本安装 iOS 构建模块：UnityHub → Installs → 您的 Unity 版本 → Add modules → iOS Build Support。
Google.IOSResolver.dll 错误
Assembly 'Packages/com.google.external-dependency-manager/ExternalDependencyManager/Editor/1.2.182/Google.IOSResolver.dll' will not be loaded due to errors:
Unable to resolve reference 'UnityEditor.iOS.Extensions.Xcode'. Is the assembly missing or incompatible with the current platform?
Reference validation can be disabled in the Plugin Inspector.

初始化​

在调用库方法之前，必须初始化客户端单例。

初始化 InstallReferrerClient
InstallReferrerClient.Instance.Init();

获取 InstallReferrer 对象​

调用 GetInstallReferrer() 以获取 InstallReferrer：

调用 GetInstallReferrer 方法
InstallReferrerClient.Instance.GetInstallReferrer(
    onFailure: (error) => {
        // Process error
    },
    onSuccess: (result) => {
        // Process result
    });
})

  • 在收到 onSuccess 响应时，如果您计划使用 InstallReferrer，请将其值保存在您的应用程序中。 再次请求时，将返回 null 而非 InstallReferrer 的值。

    备注

在以下情况下，InstallReferrer 的值为 null：

  • 应用程序在安装时未传递 referrer。

  • 之前已请求过 InstallReferrer。

  • 自 RuStore 收到 referrer 以来已过去 10 天或更多。 :::

  • 在收到 onFailure 响应时，请根据您的应用程序逻辑处理错误。 所有可能的错误均在可能出现的错误章节中描述。

InstallReferrer 类
public class InstallReferrer {

    public long installAppTimestamp { get; }
    public string packageName { get; }
    public long receivedTimestamp { get; }
    public string referrerId { get; }
    public long? versionCode { get; }
    public string? utmCampaign { get; }
    public string? utmGroup { get; }
    public string? utmBanner { get; }
	
    ...
}
  • installAppTimestamp — 应用程序安装时间（时间戳形式）。
  • packageName — 应用程序的包名。
  • receivedTimestamp — 接收到 referrer 数据的时间（时间戳形式）。
  • referrerId — referrer 标识符。
  • versionCode — 应用程序的版本代码（如果可用）。
  • utmCampaign — 广告活动名称。
  • utmGroup — 广告组名称。
  • utmBanner — 横幅广告标识符。

推荐链接的格式示例：

https://www.rustore.ru/catalog/app/ru.rustore.installreferrer?referrerId=test0&utm_campaign=test1&utm_group=test2&utm_banner=test3

将信息传输至 VK 广告 Full Stream Attribution​

Full Stream Attribution 是一项能够确保将用户信号几乎实时地从广告主传输到 VK 广告优化系统的技术。 这使得模型能够真正地以实时模式调整投放策略，并高精度地匹配特定用户的兴趣。

RuStore Install referrer SDK 从 10.3.0 版本起，支持将已登录用户的电话号码（从 10.0.0 版本起）、授权令牌和事件类型传输到 Full Stream Attribution 系统。

如需在 SDK 中传输电话号码、授权令牌和事件类型，请使用以下方法：

调用 FsaEvent 方法
var phoneNumber = new PhoneNumber("81234567890");
var authToken = "Token";
var fsaEventType = new FsaEventType.ViewOffer("product_id");

var fsaEvent = new FsaEvent(phoneNumber, authToken, fsaEventType);

InstallReferrerClient.Instance.SendFsaEvent(
    fsaEvent: fsaEvent,
    onFailure: (error) => {
        // Process error
    },
    onSuccess: () => {
        // Process success
    }
);
  • fsaEvent —— Full Stream Attribution 的事件数据。

传输电话号码并非强制要求，且除非在 SDK 中明确启用该功能，否则该功能将不生效。 此外，为了将电话号码发送到 Full Stream Attribution 系统，必须向 SDK 传递授权令牌 (authToken)。

提示

授权令牌 authToken 需要向 VK 广告经理申请。

SDK 将 FsaEvent 数据传输至 VK 广告服务器。

FsaEvent 类
public class FsaEvent : BaseFields {

    public PhoneNumber phoneNumber { get; }
    public string authToken { get; }
    public FsaEventType eventType { get; }

    public FsaEvent(
        PhoneNumber phoneNumber,
        string authToken,
        FsaEventType eventType
    ) { ... }
}
  • phoneNumber —— 电话号码。
    • 正确号码示例：
      • 79991234567 — 正好 11 位数字。
      • +7 (999) 123-45-67 — 标准化后为 11 位数字。
      • 8(999)1234567 — 标准化后为 11 位数字。
    • 错误号码示例：
      • 123 — 太短（3 位数字）。
      • 12345678901234567890 — 太长（20 位数字）。
      • abc-def — 标准化后为 0 位数字。
  • authToken — 授权令牌。
  • eventType — 事件类型。
FsaEventType 类
public abstract class FsaEventType {
    public static string NameOf<T>() where T : FsaEventType => typeof(T).Name;

    private FsaEventType() { }

    public sealed class Install : FsaEventType {
        public Install() { }
    }
	
    public sealed class ViewOffer : FsaEventType {
        public string productId { get; }
        public ViewOffer(string productId) {
            this.productId = productId;
        }
    }

    public sealed class AddToCart : FsaEventType {
        public string productId { get; }
        public AddToCart(string productId) {
            this.productId = productId;
        }
    }

    public sealed class Purchase : FsaEventType {
        public string productId { get; }
        public Purchase(string productId) {
            this.productId = productId;
        }
    }

    public sealed class AddToWishlist : FsaEventType {
        public string productId { get; }
        public AddToWishlist(string productId) {
            this.productId = productId;
        }
    }
}
  • Install — 安装应用程序 / 首次授权。
  • ViewOffer — 查看优惠。
  • AddToCart — 添加到购物车。
  • Purchase — 购买。
  • AddToWishlist — 添加到愿望清单。

VKR 分析​

VKR (VK Referrer Analytics) — 附加分析功能，在调用 getInstallReferrer() 时会自动发送推荐来源数据。

激活条件​

仅当应用程序的 AndroidManifest.xml 中添加了元标签时，VKR 才会运行：

<meta-data
    android:name="ru.rustore.sdk.install.referrer.ENABLE_VKR_ANALYTICS"
    android:value="true" />

如果缺少元标签，则 VKR 将被完全禁用。

行为​

  • 如果在 getInstallReferrer() 成功且获取到非空推荐来源时，它会自动启动。
  • 它会传输 referrerId、UTM 字段、当前时间戳和 GAID (Google Advertising ID)。
  • VKR 错误不会影响 getInstallReferrer() 的结果 —— 它们在 SDK 内部被抑制。

可能的错误​

  • RuStoreNotInstalledException — 用户设备上未安装 RuStore。

  • RuStoreOutdatedException — 用户设备上安装的 RuStore 版本不支持此 SDK。

  • RuStoreException — RuStore 基础错误，其他错误均继承自此类。

  • InstallReferrerException.ClientNotCreated — 创建 Install Referrer 客户端时出错。

  • InstallReferrerException.InvalidPhoneNumberException — 电话号码格式不正确。