Hawk Guides
Chunk #0
In this page you’ll find links to user documentation for Hawk, our LiveOps system:
- [Payments and Shop Configuration in Hawk](/wiki/spaces/KB/pages/2916810950/Payments+and+Shop+Configuration+in+Hawk)
- [Configuring Events](/wiki/spaces/KB/pages/3583279198/Configuring+Events)
- [Recurring Events](/wiki/spaces/KB/pages/4124311574/Recurring+Events)
- [Parameter sets](/wiki/spaces/KB/pages/4124115050/Parameter+sets)
- [Activity Sets](/wiki/spaces/KB/pages/4124180493/Activity+Sets)
- [Advanced Scenarios](/wiki/spaces/KB/pages/4123656278/Advanced+Scenarios)
- [Parameters and Activity Templates](/wiki/spaces/KB/pages/4124409886/Parameters+and+Activity+Templates)
- [Configuring Activities](/wiki/spaces/KB/pages/3652321290/Configuring+Activities)
- [Objectives](/wiki/spaces/KB/pages/4124508203/Objectives)
- [Client Leaderboards](/wiki/spaces/KB/pages/4123721814/Client+Leaderboards)
- [Collection Sets](/wiki/spaces/KB/pages/4124704819/Collection+Sets)
- [Dynamic Races](/wiki/spaces/KB/pages/4124704829/Dynamic+Races)
- [Leagues](/wiki/spaces/KB/pages/4124213297/Leagues)
- [Navigation Help for the User Guide](/wiki/spaces/KB/whiteboard/4131192852)
- [Onboarding Events](/wiki/spaces/KB/pages/4367319345/Onboarding+Events)
- [Campaigns & App Links in Hawk](/wiki/spaces/KB/pages/3622731872/Campaigns+App+Links+in+Hawk)
- [A/B Experiments in Hawk](/wiki/spaces/KB/pages/3319988247/A+B+Experiments+in+Hawk)
Payments and Shop Configuration in Hawk
Chunk #0
**Introduction**
In this guide you’ll learn:
- How to configure Game Products and Shop Products
- How to configure a shop in your game
- How to configure payments
**Table of Contents**
* * *
## Payments in Hawk
Payments is the section that allows you to configure in-app purchases (IAP) in your game.
There are two main types of in-app purchases that can be made in Tripledot’s games:
- **Consumables:** assets that provide further progress in a game like gems, coins, chips, etc. Consumable in‑app purchases are depleted as they’re used and can be purchased again. An example of consumable assets are extra chips in Blackjack, coins in Woodoku, etc.
- **Non-consumables:** non-consumables are premium features that are purchased once and don’t expire. Examples include additional filters in a photo app, characters' new clothes/weapons in a game, etc. The main check here is to ensure that non-consumable purchase is saved through updates and reinstall, and cannot be purchased multiple times. An example of a non-consumable asset would be being able to pay so that no ads are shown in Blackjack.
However, please note that Hawk does not make any difference in practical terms regarding these two types of IAPs.
## Game Products and Shop Products in Hawk
Game Products and Store Products are the core of the Payments system in Hawk.
Game Products are the actual bundles of items to sell in your shop. Store products are the bundles with the price point to sell in the device app store, and all of them are composed of **Game Items** , which are created in **Game Server.**
### Configuring Game Items
Game Items, which are the consumable elements that can be bundled in Store Products and purchased in the App Store, **are configured in Game Server. **
1. In your game, navigate to Game Items, and click **[New]**.
2. Add a name to your item and select the type of item. Click **[Save]** when you’re done.
Once the items have been created in Game Server, it’s time to configure them in Hawk.
**About Game Items**
- The type of items that can be configured are determined by the Client.
- Game Items are created in Game Server because they are part of the core logic of the games, and are game-specific. Hawk, on the other side, as a Live Ops system, it can only operate with these items, but not create them.
- Game Items are synchronised with Hawk every hour, but this can be manually forced by clicking **[Synchronize]** in **Hawk \> Payments \> Game Items**
### Creating Game Products
As mentioned above, a **Game Product is the bundle of Game Items** that can be sold as an offer in the game. These bundles are **created in Hawk** , and can have more than one type of item inside (this depends on the configuration of your game).
To configure Game Products, follow these steps:
1. In Hawk, navigate to your Game, and select **Payments \> Game Products**. In this page you’ll be able to see the existing products, and where are they being used. Game Products can be used in more than one store, and the display name is localisable.
2. Click **[+ Add Game Product]** to create a new bundle. Add a new name, select a localisation key (if required, called Display Name Key in Hawk), and select a Product Image.
3. Then, click **[+Add]** to create your bundle of items. From the dropdown, select your item, and type in the amount. Click **[+Add]** again to add more items.
**About Localisation Keys and Product Images**
- The display name of the Game Product can be localised, however, the contents are not localisable. Localisation Keys are created and synchronised from Game Server. Read [this page](/wiki/spaces/KB/pages/3230760961/Managing+Localisations+in+Harmony) to know more.
- Product Images are created in Hawk. To add a new image, navigate to **Payments \> Product Images** , and upload a new image.
### Configuring Store Products
Store Products are the abstract entity of Game Products that is used on the device App Store, such as App Store for iOS or Google Play Store for Android. Store Items have the price point that will be used in the device App Store, and they are also used in Catalogs to determine the price of the items in the shop.
To create a new Store Product, follow the steps below:
1. In your game, navigate to **Payments \> Store Products**. In this page you’ll be able to see the existing products, their prices and in which catalogs they’re being used. To create a new Product, click **[+Add Store Product]** on the upper right corner of the screen.
2. Then, add a price point, and the Store ID will be generate automatically following the naming convention. Click **[Save]** when you’re done.
**Store Products Naming Convention**
The naming convention for Store Products is the following: `<denominator>_package_<game>`
Example: `0.99_package_woodoku`
## Creating a Catalog in Hawk
Catalogs are where you configure the items to sell in your shop. Catalogs are A/B testable and can be targeted to different segments of users.
**About Segments in Catalogs**
Remember that **Catalogs are created per segment**. If you’d like to create a different shop for another segment, please create a new Catalog.
1. In Hawk, select your app from the dropdown menu, and then navigate to **Payments \> Catalogs.** Click **[+ Add Catalog]** to create a new one.
2. Add a name to your catalog, assign a status and availability. Assign it to an existing segment and provide it with a priority.
3. Click the **“Edit configuration”** toggle to start configuring your shop. Once enabled, click **[+Add]** to add products.
4. Then, fill in the fields. A description of each of the fields can be found in the table below:
| **Field** | **Description** | **Validations** |
| **ID Product** | The product you will be selling in the store. The data in this field comes from Game Items | Dropdown with the game products to sell |
| **Price Type** | The type of item you are selling in the store. | - Store Product - In-game Currency - Ads - Free |
| **Price** | The price of the bundle in the App Store. This information comes from the items in Store Products. | Dropdown |
| **Platform** | The App Store where you want to sell your items. | - All - iOS - Android |
| **Line Group** | This field determines where in the shop your catalog will be located. Shop Items with the same Line Group will be presented in the same line to players. | Number |
| **Label** | Label to appear in the App Store, which are used to highlight a special offer or similar. They can be configured from **Payments \> Product Labels.** | Dropdown with existing labels  |
| **Purchase restrictions** | This field determines how many times can the item be purchased by the player. | - **None:** no restrictions apply - **Purchase Limit:** Integer value for the number of items that can be purchased/claimed - **Purchase Cooldown:** Time between two consecutive items are available for purchase/claim. Specify the time in hours and minutes. |
| **Sale Type** | This field determines the type of sale that applies to this shop. Not applicable for Ads or Free items. | - **None:** no special sale - **More Value:** more products for the same price. - **Price Cut:** lower price. If this is selected, a new dropdown will appear where you can select a new price. - **Extra Amount:** more items for the same price.  |
| **Sale Value** | Value that is charged for the sale. | You can specify the sale value based on the sale type. It is to be specified as a % value for more value type and in float form for price cut and extra amount sale types. |
| **Items Rounding Type** | This field is enabled if “More value” is selected under sale type. The calculation is determined by the Client development Team. | - **Round up** - **Round down** - **Math rounding:** chooses the number closer to 0 or 1 as determined by the client dev team. |
**Do you need support?**
If you need support, you can obtain the Entity Variant ID from any Catalog. This will help the Hawk team identify better your issue.
## Configuring Presets
Presets are specific **reusable stores** that are intended to be used for recurring or seasonal sales. These Presets will appear under **Catalogs \> Shop** and even though they target the same segment of users, they offer a different set of products.
To configure a new Preset, navigate to **Payments \> Presets**. In this section, you’ll be able to see the existing presets and in which catalog they’re being used. The short video below shows to create a preset.
Once the preset has been created, it will be available to use and configure in any Catalog:
Payments and Shop Configuration in Hawk
Chunk #2
Configuring Purchase Limits in the Catalog
As a Hawk user, you can configure purchase limits for game products to simplify client-side logic by managing purchase restrictions within Hawk. This feature allows you to define purchase limits on game products and ensures that these limits are enforced without additional client-side complexity.
To configure the purchase limits:
1. Navigate to the **Payments** Section.
2. From the left-hand menu, click on **Catalogs** under the Payments section.
3. A list of existing catalogs will appear on the screen.
4. Select a catalog to edit or add a new catalog.
5. The catalog's detailed configuration panel will appear at the bottom of the screen.
6. Scroll down to the **Entity Variant ID** section, where you'll see various configuration settings for products.
7. Switch on the **Edit Configuration** toggle.
8. In the product table under the **Expanded View** , locate the column labeled **Purchase Restrictions**.
9. Find the relevant product in the list (identified by its ID and Product name).
10. Select the **Purchase Limit** option and input the number of times the product can be purchased by a player.
11. Optional: Configure Additional Fields (If Needed).
**Price Type:** Select the type of price (Store product, etc.).
**Price:** Enter the price for the product.
**Platform:** Select the platforms where the product will be available (All, iOS, Android, etc.).
**Label:** Set a label for the product (e.g., Best Value).
**Sale Type & Sale Value:** If any discounts or sales are applied to the product, you can configure them here.
12. After setting the **Purchase Limit** and other configurations as needed, scroll to the bottom and click the **Save** button.
13. The updated purchase limit settings will now be applied to the selected catalog.
### Purchase Limit: Different Scenarios.
**Scenario:** A game product in the catalog has a purchase limit set to 1.
- When the player purchases the game product,
- Then the player will not be able to purchase the item again (the purchase limit has been reached). Once the purchase limit is reached, the server will no longer serve the game product in the store response.
- **Note:** If the purchase limit is set to **None** , there are no restrictions, and the player can purchase the item multiple times.
**Adjusting Purchase Limits in a Live Entity**
S **cenario A:** Increasing Purchase Limit
- Context: A game product in the catalog has a purchase limit.
- When the player has already purchased the maximum quantity of the product based on the purchase limit,
- And the purchase limit is increased,
- Then the product will become available in the store for the player to purchase again.
**Scenario B:** Decreasing Purchase Limit
- Context: A game product in the catalog has a purchase limit, and the player still has the availability to purchase the game product.
- When the purchase limit is decreased,
- Then the player will no longer see the product in the store (if the new limit has already been met or exceeded).
### Catalog Product ID Attribute
- Context: Game products in the catalog now include a new attribute, `catalog_product_id`, which is a unique identifier for each item across different catalogs.
- Action: The `catalog_product_id` will be passed as an optional parameter with the `purchase_success` trigger to identify the specific product.
### **Tracking Purchases with Limitations**
Hawk will track how many purchases a player has made for specific game products with purchase limitations.
### **Player Page Updates**
In the **Purchases** section, a new table will be available to view purchase limits. The table will show:
- Game products currently available to the player with a purchase limit.
- Historical game products with a purchase limit were served to the player.
### Handling Segment and Catalog Switching
**Scenario:** A game product is restricted by a purchase limit across different player segments.
- Context: A game product (X) is in catalog A, which is assigned to segment A, and it has a purchase limit set to 1.
- When the player, belonging to segment A, purchases game product X,
- And the product is no longer available to the player due to the purchase limit being reached,
- And the player switches segments to segment B (served by catalog B),
- And later switches back to segment A (served by catalog A),
- Then game product X will still not be available in catalog A for the player, as the purchase limit has already been reached.
- **Live Entity Adjustments:** Changes to purchase limits in the live entity will dynamically affect the product availability in the store for players.
- **Unique Product Tracking:** The `catalog_product_id` ensures each product is tracked uniquely across various catalogs, preventing overlap or misidentification in cross-segment product offerings.
* * *
## 🔍 Frequently Asked Questions
**About Payments Database**
All the information about Payment Intents/Payment Success can be found in Looker. For further information, please contact the BI/DS&E teams.
In Redash, you can also access to the information for transactions and intents. To do so, please look for:
- `gs_payments_transactions`
- `gs_payments_intents`
- **How does a user qualify to receive Catalogs?**