Users

A user represents an individual who interacts with your app.

Users

To complete integration, you must register users of your app in WinWinKit via our SDK or REST API..

User Properties

Configurable

These are the properties that you can use to update your user entities in WinWinKit.

App User Id (Required)

The only mandatory property that uniquely identifies a user within your app and in WinWinKit.

Normally it is a universally unique identifier (UUID).

Is Premium

Flag determining the premium status of a user.

The is_premium flag serves an important purpose of tracking:

We recommend updating it whenever user’s premium status changes.

To handle trial users properly, read more about Is Trial flag below.

For automatic updates of the is_premium flag, enable integration with RevenueCat. To do this, go to your project in WinWinKit and navigate to Settings -> Integrations page.

Is Trial

Flag determining the trial status of a user. Helps to improve conversion tracking accuracy by filtering out users who are still in trial.

We recommend updating it whenever user’s trial status changes.

When both is_premium and is_trial are set to true, the user is considered a trial user, and no conversion is tracked.

For automatic updates of the is_trial flag, enable integration with RevenueCat. To do this, go to your project in WinWinKit and navigate to Settings -> Integrations page.

First Seen At

Date when the user was first seen in your app.

Used to determine user’s eligibility to claim a referral code. Learn more about Claim Code Elibigility

Metadata

A metadata object.

This allows you to provide extra configuration and metadata making it flexible to meet your specific needs. Must be a valid JSON object.

Provided by WinWinKit

These are the properties provided by WinWinKit that reflect user’s referral data, active and expired rewards, and stats.

Referral Code

Unique referral code for the user.

A referral code is always 6 characters long and consists of a combination of letters and numbers.

The code is unique within your app.
Is assigned once and never changes.

Example: XYZ123

A web url to the referral code and its rewards which your app users can share with friends.

Learn more about how to set up Code Link.

Example: https://appname.wwk.link/XYZ123

Referral Program

An object containing complete information about the referral program assigned to the user. Can be used to create dynamic user interface based on the program configurations.

Claim Code Eligibility

An object providing information about user’s eligibility to claim a referral code.

An eligible user is allowed to claim a referral code.

Eligibility Rules

Currently, WinWinKit implements a few simple rules for limiting the types of users eligible to claim a referral code.

  • A user must not be older than 7 days.

    Because referral is for inviting new users, this restricts users from getting rewards without referring new users.

    The reference date used is the First Seen At, if provided; otherwise, the date when the user was created in WinWinKit is used.

    Does this rule seem reasonable? If not, we would love to hear your feedback.

  • The program limit has not been reached.

    The reference program here is referring user’s program. Read more about Programs Limit configuration.

    By default there is no limit, and it must be specified for this rule to apply.

  • A user can claim a code only once.

  • A user cannot claim own code.

You can impose further limitations on a user’s ability to claim a referral code, but cannot prolong elibility conditions imposed by WinWinKit. Once a user is not eligible according to WinWinKit, there is no override.

If a user attempts to claim a referral code when not eligible, WinWinKit provides a descriptive message explaining the reason for the decline.

Example

The eligible field indicates whether the user can claim the referral code, while eligible_until specifies the expiration date.

"claim_code_eligibility": {
  "eligible": true,
  "eligible_until": "2025-02-10T10:28:18.104Z"
}

Stats

An object with information about referral statistics for the user.

Provides three values:

  • Claims - how many invited users claimed the user’s referral code.
  • Conversions - how many of those who claimed the user’s referral code became premium users.
  • Churns - how many of those who claimed the user’s referral code became premium users and then churned.

Correct tracking of Conversions and Churns requires updating Is Premium flag.

Example

"stats": {
  "claims": 10,
  "conversions": 8,
  "churns": 1
}

Rewards

A list of active and expired rewards for the user.

Remember to unlock access to the active rewards in your app. 
"rewards": {
  "active": {
    "basic": [
      {
        "reward": {
          "key": "app-icon-neon",
          "name": "App Icon Neon",
          "description": "Access to an exclusive app icon",
          "metadata": null,
          "created_at": "2021-01-01T00:00:00.000Z",
          "updated_at": "2021-01-01T00:00:00.000Z"
        },
        "expires_at": null,
        "created_at": "2021-01-01T00:00:00.000Z",
        "updated_at": "2021-01-01T00:00:00.000Z"
      }
    ],
    "credit": [
      {
        "reward": {
          "key": "20-ai-requests",
          "credits": 20,
          "name": "20 AI Requests",
          "description": "Access to extra AI requests",
          "metadata": null,
          "created_at": "2021-01-01T00:00:00.000Z",
          "updated_at": "2021-01-01T00:00:00.000Z"
        },
        "credits": 20,
        "expires_at": "2021-01-01T00:00:00.000Z",
        "created_at": "2021-01-01T00:00:00.000Z",
        "updated_at": "2021-01-01T00:00:00.000Z"
      }
    ],
    "offer_code": [
      {
        "reward": {
          "key": "free-month",
          "offer_code_id": "123e4567-e89b-12d3-a456-426614174000",
          "name": "Free Month",
          "description": "Receive a free month of a subscription",
          "metadata": null,
          "created_at": "2021-01-01T00:00:00.000Z",
          "updated_at": "2021-01-01T00:00:00.000Z"
        },
        "value": {
          "value": "ABCDEFGHIJKLMNOPQR",
          "link": "https://apps.apple.com/redeem?ctx=offercodes&id=1234567890&code=ABCDEFGHIJKLMNOPQR",
          "expires_at": "2021-01-01T00:00:00.000Z"
        },
        "expires_at": "2021-01-01T00:00:00.000Z",
        "created_at": "2021-01-01T00:00:00.000Z",
        "updated_at": "2021-01-01T00:00:00.000Z"
      }
    ]
  },
  "expired": {
    "basic": [],
    "credit": [],
    "offer_code": []
  }
}

Example

Below is an example of a full referral user object returned by the REST API.

{
  "data": {
    "user": {
      "app_user_id": "821fae4b5-1a2d-4c1e-9152-5297086a161c",
      "referral_code": "XYZ123",
      "referral_code_link": "https://appname.wwk.link/XYZ123",
      "is_premium": false,
      "first_seen_at": "2024-11-10T10:28:18.104Z",
      "metadata": {},
      "claim_code_eligibility": {
        "eligible": true,
        "eligible_until": "2024-11-10T10:28:18.104Z"
      },
      "stats": {
        "claims": 0,
        "conversions": 0,
        "churns": 0
      },
      "rewards": {
        "active": {
          "basic": [
            {
              "reward": {
                "key": "basic-reward",
                "name": "Basic Reward",
                "description": "This is a basic reward",
                "metadata": {},
                "created_at": "2021-01-01T00:00:00.000Z",
                "updated_at": "2021-01-01T00:00:00.000Z"
              },
              "expires_at": "2021-01-01T00:00:00.000Z",
              "created_at": "2021-01-01T00:00:00.000Z",
              "updated_at": "2021-01-01T00:00:00.000Z"
            }
          ],
          "credit": [
            {
              "reward": {
                "key": "credit-reward",
                "credits": 100,
                "name": "Credit Reward",
                "description": "This is a credit reward",
                "metadata": {},
                "created_at": "2021-01-01T00:00:00.000Z",
                "updated_at": "2021-01-01T00:00:00.000Z"
              },
              "credits": 100,
              "expires_at": "2021-01-01T00:00:00.000Z",
              "created_at": "2021-01-01T00:00:00.000Z",
              "updated_at": "2021-01-01T00:00:00.000Z"
            }
          ],
          "offer_code": [
            {
              "reward": {
                "key": "offer-code-reward",
                "offer_code_id": "123e4567-e89b-12d3-a456-426614174000",
                "name": "Offer Code Reward",
                "description": "This is an offer code reward",
                "metadata": {},
                "created_at": "2021-01-01T00:00:00.000Z",
                "updated_at": "2021-01-01T00:00:00.000Z"
              },
              "value": {
                "value": "ABCDEFGHIJKLMNOPQR",
                "link": "https://apps.apple.com/redeem?ctx=offercodes&id=1234567890&code=ABCDEFGHIJKLMNOPQR",
                "expires_at": "2021-01-01T00:00:00.000Z"
              },
              "expires_at": "2021-01-01T00:00:00.000Z",
              "created_at": "2021-01-01T00:00:00.000Z",
              "updated_at": "2021-01-01T00:00:00.000Z"
            }
          ]
        },
        "expired": {
          "basic": [
            {
              "reward": {
                "key": "basic-reward",
                "name": "Basic Reward",
                "description": "This is a basic reward",
                "metadata": {},
                "created_at": "2021-01-01T00:00:00.000Z",
                "updated_at": "2021-01-01T00:00:00.000Z"
              },
              "expired_at": "2021-01-01T00:00:00.000Z",
              "created_at": "2021-01-01T00:00:00.000Z",
              "updated_at": "2021-01-01T00:00:00.000Z"
            }
          ],
          "credit": [
            {
              "reward": {
                "key": "credit-reward",
                "credits": 100,
                "name": "Credit Reward",
                "description": "This is a credit reward",
                "metadata": {},
                "created_at": "2021-01-01T00:00:00.000Z",
                "updated_at": "2021-01-01T00:00:00.000Z"
              },
              "expired_at": "2021-01-01T00:00:00.000Z",
              "created_at": "2021-01-01T00:00:00.000Z",
              "updated_at": "2021-01-01T00:00:00.000Z"
            }
          ],
          "offer_code": [
            {
              "reward": {
                "key": "offer-code-reward",
                "offer_code_id": "123e4567-e89b-12d3-a456-426614174000",
                "name": "Offer Code Reward",
                "description": "This is an offer code reward",
                "metadata": {},
                "created_at": "2021-01-01T00:00:00.000Z",
                "updated_at": "2021-01-01T00:00:00.000Z"
              },
              "expired_at": "2021-01-01T00:00:00.000Z",
              "created_at": "2021-01-01T00:00:00.000Z",
              "updated_at": "2021-01-01T00:00:00.000Z"
            }
          ]
        }
      },
      "referral_program": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "Referral Program #1",
        "description": "This is a referral program",
        "metadata": {},
        "distribution_percentage": 100,
        "limit": 0,
        "rewards": {
          "sender": {
            "basic": [
              {
                "reward": {
                  "key": "basic-reward",
                  "name": "Basic Reward",
                  "description": "This is a basic reward",
                  "metadata": {},
                  "created_at": "2021-01-01T00:00:00.000Z",
                  "updated_at": "2021-01-01T00:00:00.000Z"
                },
                "activation": {
                  "variant": "claim",
                  "amount": 1
                },
                "deactivation": {
                  "variant": "never"
                }
              }
            ],
            "credit": [
              {
                "reward": {
                  "key": "credit-reward",
                  "credits": 100,
                  "name": "Credit Reward",
                  "description": "This is a credit reward",
                  "metadata": {},
                  "created_at": "2021-01-01T00:00:00.000Z",
                  "updated_at": "2021-01-01T00:00:00.000Z"
                },
                "activation": {
                  "variant": "claim",
                  "amount": 1,
                  "limit": 1
                },
                "deactivation": {
                  "variant": "never"
                }
              }
            ],
            "offer_code": [
              {
                "reward": {
                  "key": "offer-code-reward",
                  "offer_code_id": "123e4567-e89b-12d3-a456-426614174000",
                  "name": "Offer Code Reward",
                  "description": "This is an offer code reward",
                  "metadata": {},
                  "created_at": "2021-01-01T00:00:00.000Z",
                  "updated_at": "2021-01-01T00:00:00.000Z"
                },
                "activation": {
                  "variant": "claim",
                  "amount": 1,
                  "limit": 1
                },
                "deactivation": {
                  "variant": "never"
                }
              }
            ]
          },
          "receiver": {
            "basic": [
              {
                "reward": {
                  "key": "basic-reward",
                  "name": "Basic Reward",
                  "description": "This is a basic reward",
                  "metadata": {},
                  "created_at": "2021-01-01T00:00:00.000Z",
                  "updated_at": "2021-01-01T00:00:00.000Z"
                },
                "activation": {
                  "variant": "claim"
                },
                "deactivation": {
                  "variant": "never"
                }
              }
            ],
            "credit": [
              {
                "reward": {
                  "key": "credit-reward",
                  "credits": 100,
                  "name": "Credit Reward",
                  "description": "This is a credit reward",
                  "metadata": {},
                  "created_at": "2021-01-01T00:00:00.000Z",
                  "updated_at": "2021-01-01T00:00:00.000Z"
                },
                "activation": {
                  "variant": "claim"
                },
                "deactivation": {
                  "variant": "never"
                }
              }
            ],
            "offer_code": [
              {
                "reward": {
                  "key": "offer-code-reward",
                  "offer_code_id": "123e4567-e89b-12d3-a456-426614174000",
                  "name": "Offer Code Reward",
                  "description": "This is an offer code reward",
                  "metadata": {},
                  "created_at": "2021-01-01T00:00:00.000Z",
                  "updated_at": "2021-01-01T00:00:00.000Z"
                },
                "activation": {
                  "variant": "claim"
                },
                "deactivation": {
                  "variant": "never"
                }
              }
            ]
          }
        },
        "created_at": "2021-01-01T00:00:00.000Z",
        "updated_at": "2021-01-01T00:00:00.000Z"
      }
    }
  }
}