Yousie SDK documentation

1. What the SDK does

Yousie is a platform where brands list a mobile app and creators promote it. Each creator gets a personal tracking link to the app’s store page. The Yousie SDK (software development kit) is a small library inside your app. It tells Yousie which installs and which subscriptions came through those links, in two steps:

1. The install. On the first launch the SDK reads the Google Play install referrer: the text Google Play hands to an app that was installed from a link. If the install came through a creator’s link, the referrer carries a click ID (yclid), and the SDK reports the install to Yousie once. Yousie then attributes it: it credits the install to that click, and so to the creator.
2. The subscription. When that install buys a subscription, the SDK reports it. Yousie books it as pending.

Confirming subscriptions stays your job. A pending subscription counts only once you confirm it: by hand on the page of your campaign (the offer creators join for your app), or from your server with your postback secret, a key only your server holds (section 4). The SDK never holds that secret.

An install that did not come through a Yousie link costs one referrer read on the first launch and nothing afterwards: no network call, no billing connection.

2. Before you start

Your SDK key

The SDK key says which app is reporting. It starts with ysk_. In your dashboard, open My Apps, open your app, and copy SDK key from the Tracking keys panel. The key is public, so it is safe to ship inside your app.

No app on Yousie yet? Create a brand account, then add your app in My Apps.

Your other key is the postback secret, which starts with yss_. Yousie shows it once, when the app is added, and again only when you create a new one in the same panel. It stays on your server, never inside the app.

Your Android package

The Android package of your app on Yousie must be your app’s real package: the application ID it has on Google Play, such as com.example.app. A creator’s link sends people to the Google Play page of that package, and Google Play hands the referrer only to the app installed from that page. With a wrong package the link opens the wrong page, and no install is attributed.

Check it on your app’s page in My Apps, under App details, in the field Android package. It cannot be changed once the app is added.

Requirements

• Android 5.0 (API 21) or newer.
• Android only. On iOS the Flutter calls do nothing.
• Automatic purchase tracking needs Google Play Billing Library 7 or newer in your app (Google’s library for in-app purchases). With an older one, or to send the price and the trial, call trackSubscription yourself.
• For the Flutter plugin: Flutter 3.47 or newer, and Android 7.0 (API 24) or newer.

3. Add tracking to your app

Choose how your app talks to Yousie. With the SDK there are five steps: install, start, consent, subscriptions, test. On iPhone there is no SDK: the iPhone tab says how installs are counted there.

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://jitpack.io") }
    }
}

dependencies {
    implementation("com.github.Yousie-com:yousie-sdk:1.0.0")
}

import android.app.Application
import com.yousie.sdk.Yousie
import com.yousie.sdk.YousieConsent

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        Yousie.init(this, "ysk_your_sdk_key", YousieConsent.GRANTED)
    }
}

// App with a consent form: start with UNKNOWN, then state the answer.
Yousie.init(this, "ysk_your_sdk_key", YousieConsent.UNKNOWN)
// later, when the user has answered:
Yousie.setConsent(YousieConsent.GRANTED)   // or YousieConsent.DENIED

Yousie.trackSubscription(
    productId = "premium_yearly",
    orderId = purchase.orderId,
    purchaseToken = purchase.purchaseToken,
    price = 29.99,
    currency = "EUR",
    trial = true,
)

import com.yousie.sdk.YousieOptions

Yousie.init(
    this, "ysk_your_sdk_key", YousieConsent.GRANTED,
    YousieOptions(
        autoTrackPurchases = true,   // false: only trackSubscription() reports purchases
        logging = false,             // true: prints what the SDK does under the logcat tag "Yousie"
    ),
)

import com.yousie.sdk.YousieOptions

Yousie.init(
    this, "ysk_your_sdk_key", YousieConsent.GRANTED,
    YousieOptions(
        logging = true,
        debugReferrer = "utm_source=yousie&utm_medium=affiliate&utm_campaign=<code>&yclid=<click id>",
        debugReset = true,   // forget the SDK's saved state at each start, so the flow replays
    ),
)

adb logcat -s Yousie

dependencies:
  yousie:
    git:
      url: https://github.com/Yousie-com/yousie-sdk.git
      path: flutter
      ref: 1.0.0

import 'package:yousie/yousie.dart';

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  Yousie.init(sdkKey: 'ysk_your_sdk_key', consent: YousieConsent.granted);
  runApp(const MyApp());
}

Yousie.setConsent(YousieConsent.granted); // or YousieConsent.denied / YousieConsent.unknown

Yousie.trackSubscription(
  productId: purchase.productID,
  orderId: purchase.purchaseID,
  purchaseToken: purchase.verificationData.serverVerificationData,
  price: 29.99,
  currency: 'EUR',
  trial: true,
);

Yousie.init(
  sdkKey: 'ysk_your_sdk_key',
  consent: YousieConsent.granted,
  logging: true,
  debugReferrer: 'utm_source=yousie&utm_medium=affiliate&utm_campaign=<code>&yclid=<click id>',
  debugReset: true,
);

adb logcat -s Yousie

https://apps.apple.com/app/id<App Store ID>?pt=<provider ID>&ct=yousie_<link code>&mt=8

utm_source=yousie&utm_medium=affiliate&utm_campaign=<code>&yclid=<click id>

POST https://yousie.com/api/v1/installs
Content-Type: application/json

{
  "sdk_key": "ysk_your_sdk_key",
  "click_id": "<the yclid value of the install referrer>",
  "install_id": "<an ID you create once for this install>",
  "platform": "android",
  "app_version": "<your app version>"
}

{ "attributed": true, "install": "ins_…" }
{ "attributed": false, "reason": "…" }

POST https://yousie.com/api/v1/events
Content-Type: application/json

{
  "sdk_key": "ysk_your_sdk_key",
  "install_id": "<the same install ID>",
  "event": "subscription",
  "external_id": "<the order ID from the store>",
  "product_id": "<the product ID>",
  "price_micros": <the price in millionths: 4.99 is 4990000>,
  "currency": "<the currency of the price, like EUR>",
  "trial": <true or false>
}

{ "recorded": true, "conversion": "cnv_…", "status": "pending" }
{ "recorded": false, "reason": "…" }

Get a click ID for your test

A click ID is the 22 letters and digits Yousie gives each click on a creator’s link. A test needs a real one.

1. Check that your campaign is live. A link records clicks only while its campaign is live.
2. Take a link of your campaign. Its address is https://yousie.com/c/<code>, and the Creators table on the campaign’s page lists the link code of each creator who joined.
3. Open the link in a desktop browser. Yousie records the click and sends you to your app’s Google Play page. The address of that page ends with the referrer: the click ID is the 22 characters after yclid%3D.
4. Start your app, or send the request, with that click ID. A click counts for one install.

If you cannot get a click ID, write to us.

4. Confirm subscriptions from your server

A subscription your app reports is booked as pending. Once the payment is real, confirm it with your postback secret. You pay for confirmed subscriptions only.

The confirmation is a postback: a request your own server sends to Yousie, with the secret in its Authorization header.

POST https://yousie.com/api/v1/postback
Authorization: Bearer <your postback secret>
Content-Type: application/json

{
  "event": "subscription",
  "action": "confirm",
  "external_id": "<the same order ID>"
}

• external_id is the order ID the app reported. You can name the purchase by the app’s install ID instead (install_id), or send both.
• Send reject as the action to turn one down.
• If your campaign pays a share of the subscription price, the confirmation states that price, in the campaign’s currency and in millionths: 4.99 is 4990000.

POST https://yousie.com/api/v1/postback
Authorization: Bearer <your postback secret>
Content-Type: application/json

{
  "event": "subscription",
  "action": "confirm",
  "external_id": "<the same order ID>",
  "amount_micros": <the subscription price in your campaign’s currency, in millionths>
}

You can also confirm or reject each one by hand, on the campaign’s page under Campaigns in your dashboard.

Keep the secret on your server, never inside the app. If it may have leaked, create a new one in the Tracking keys panel: the old one stops working at once.

5. Consent

Consent is your user’s answer when your app asks whether it may share data about them. The SDK sends nothing until it knows that answer. You give it to init and change it with setConsent. It has three states:

The attribution window is the number of days after a click during which an install still counts. Yousie counts it from the click, whenever the answer comes: an install reported after the window is answered expired (section 7).

Whether your app has to ask, and how, depends on the law that applies to it. This page does not decide that for you.

6. Privacy

What leaves the phone

What never leaves it

The SDK never reads or sends the advertising ID, the Android ID, the device model, the purchase token itself, or any account or contact data.

What Yousie keeps

• For an attributed install: the install ID, the click ID and, through the click, the app, the campaign and the creator’s link. Then the platform, the app version, the time of the click and the time of the report.
• Where an install report came from: the two-letter country of the request, and a keyed hash of its network address (the IP address). The hash is a fingerprint made with a secret key. Yousie uses it to cap repeated installs from one address. The address itself is not stored.
• For a refused install report: the app, the click ID, the install ID, the reason, the same hash and the time. It is kept for fraud review.
• For a subscription: the order ID, the product ID, the trial flag, the price and currency as reported. Then your decision, its time, and the price you state when a confirmation needs one.

The click comes first, in a browser and outside your app: when someone follows a creator’s link, Yousie records the click ID, the platform, the country, the same keyed hash and the browser’s user agent. How long records are kept is in the privacy policy.

What you have to declare

The SDK sends this data from your users’ phones, so declaring it is your job as the app’s developer.

• Google Play’s Data safety form. The form covers what the libraries inside your app send, not only your own code. Look at two of its data types: “Device or other IDs” for the install ID, and “Purchase history” for a subscription report. Google’s instructions for the form (opened October 9, 2026) define each type.
• Your app’s privacy policy. Say that your app tells Yousie about the installs and the subscriptions that come through a creator’s link, and list the data above.

The Terms of Sale make informing your users your responsibility, and the privacy policy says what Yousie does with the data. This section is practical guidance, not legal advice.

7. Limits today

• Android only. Installs are tracked on Android today. A tap from an iPhone is counted and sent to the App Store when the brand has given its App Store ID; the install that follows is not attributed yet.
• One subscription per install. Yousie books one subscription for an attributed install. A second purchase by the same install is answered duplicate.
• One install per click. A click counts for one install, and an install is attributed once.
• The attribution window. An install counts when your app reports it within the campaign’s attribution window, counted from the click. The window is 7 days by default. You set it on the campaign’s page, in Attribution window (days), from 1 to 30 days.
• Waiting for consent. While consent is UNKNOWN, the SDK keeps a click ID for 7 days at most, whatever the window.

8. Coming next

Integrations with other platforms and with measurement partners will be documented on this page.

• iPhone: attributing each install to its link, and bringing Apple’s totals into your campaign.
• Other platforms: React Native and Unity.
• Partners: a mobile measurement partner (MMP) is a company whose code inside your app records where installs come from. AppsFlyer, Adjust, Branch and RevenueCat are examples of the partners we will add here.

Need one of them for your app? Write to us.

9. Troubleshooting

The API answers every report it accepts with a 200 and says what it did with it. The answers below are its own words.

Answers to an install report

Answers to a subscription report

Errors

A call the API does not accept gets an error status, with the reason in the body’s error.

A sideloaded build gets no referrer

Google Play hands the referrer only to an app installed from its store page. A build installed from Android Studio, with adb or from a file has none, so the SDK finds no click ID and reports nothing. In a debuggable build, hand it one with debugReferrer, as the test step of section 3 shows. The path through the store itself can only be checked with a build installed from Google Play through a creator’s link.

Nothing in logcat

• Logging is off by default. Turn it on with the logging option.
• Filter on the SDK’s tag: adb logcat -s Yousie.
• Check that Yousie.init runs: on Android in Application.onCreate, in the Application class your manifest names, and on Flutter in main.
• debugReferrer and debugReset work in a debuggable build only. A release build ignores them.
• On an iPhone the Flutter calls do nothing.

Still stuck? Write to us with your app’s package and what the API answered.