Quickstart

Step 1: Set up your app’s products in the Mage configuration portal

To set up your app in the Mage configuration portal, you need to complete three easy steps:

1.1: Add your app

Let us know the details about your app, like Bundle-ID, Name, Categories and shipped Platforms.

Figure 1:  Adding an app to Mage

Note: The Web-API for your Web-App is still under development but will be released soon.

1.2: Add product groups

Note: Using product groups is essential for a sophisticated price optimization with Mage. Price relationships within each group will be kept stable as you don’t want your lifetime membership to become cheaper than your monthly subscription price. This way, Mage can also make better pricing predictions for the same set of products.

Define a product group to group your products with similar features in a collection.

Figure 2:  Adding a product group to Mage

1.3: Add products

Finally, add your products with your product details like the in-app purchase type, special subscription details (only relevant for subscriptions) as well as the price range in which Mage should operate.

Regarding the operational window for Mage you will define a default price and a minimum price. Mage will use your default price as the starting point for its optimization.

See our guide on Mage Portal Setup for more information and best practices.

Note: Product examples are a monthly subscription, a yearly subscription, a lifetime pro membership, an in-app purchase for a particular feature or product, etc.

Figure 3:  Adding a product to Mage

Note: Subscription characteristics (product period, free introductory offer, discounted introductory offer as well as discounted introductory offer price) are currently not optimized, but will be included in future product releases.

Step 2: Set up new in-app purchases at the app stores

As soon as you added your products, Mage will generate a set of In-App Purchase (IAP) objects as a reasonable price range for your products. To make them available for the Mage SDK, you need to add those IAPs to your app in iTunes Connect and/or Google Play Console.

You just need to add those IAPs once, and then Mage can distribute these prices according to our analysis. See App Store Setup for how to configure your in-app purchases and what to watch for.

Figure 4: Overview of In-App Purchase objects

Note for Apple Subscription Products only: To prevent your users from switching to a different subscription price, you need to create Subscription Groups inside iTunes Connect. Therefore add for each subscription group you already have in your iTunes Connect for each price level Mage defined a separate subscription group. You can find a more detailed description with examples here.

Note for Apple In-App Purchases only: Apples iTunes Connect Testers may hold back an update if they can’t find your new added in-app purchases. To prevent that, submit the in-app purchase screenshots from the default products to all new in-app purchase products. Write in the “Notes for Testers” section that you implement the in-app purchases for “A/B testing” purposes.

Implement the Mage SDK

Now it’s time to integrate the Mage SDK. Currently, Mage SDKs are available in Objective-C, React Native and Java. They only require three easy calls. Read the full documentation in our open source libraries on GitHub:

Objective-C

React Native

Java

Note: In case there is currently no SDK for your development language, feel free to check out the SDK API documentation and implement it yourself or contact us which language is missing for you so we can priotize this SDK on our roadmap. The API is documented according to the openapi3.0 standard.

Step 4: Track In-App Purchase Status Updates

To better predict subscription lifetime values and identify refunded purchases, Mage provides a simple Web API to enable notifications for status updates. Suppose your backend or third party service for your subscription tracking gets notified regarding a status update. In that case, you need to inform the Mage Web API for subscription renewals, users switching subscriptions, users refunding or rebuying in-app purchases. More detail about this method can be found in our guide on IAP State Tracking.

  
    POST /v1/aparecium HTTP/1.1
    Host: https://room-of-requirement.getmage.io
    Content-Type: application/json
    
    {
      "iapIdentifier": string,
      "appUserId": string,
      "subChangeState": string,
      "stateChangeTime": int,
      "newIapIdentifier": string
    }
  

  
    POST /v1/aparecium HTTP/1.1
    Host: https://room-of-requirement.getmage.io
    Content-Type: application/json
    
    {
        "iapIdentifier": "com.example.example_app.premium",
        "appUserId": "example_user_id",
        "subChangeState": "Renew",
        "stateChangeTime": 1593705685
    }
  

  
    POST /v1/aparecium HTTP/1.1
    Host: https://room-of-requirement.getmage.io
    Content-Type: application/json
    
    {
      "iapIdentifier": "com.example.example_app.premium",
      "appUserId": "example_user_id",
      "subChangeState": "Refund",
      "stateChangeTime": 1593705685
    }
  

  
    POST /v1/aparecium HTTP/1.1
    Host: https://room-of-requirement.getmage.io
    Content-Type: application/json
    
    {
        "iapIdentifier": "com.example.example_app.premium",
        "appUserId": "example_user_id",
        "subChangeState": "Switch",
        "stateChangeTime": 1593705685,
        "newIapIdentifier": "com.example.example_app.premium_plus"
    }
  

  
    POST /v1/aparecium HTTP/1.1
    Host: https://room-of-requirement.getmage.io
    Content-Type: application/json
    
    {
      "iapIdentifier": "com.example.example_app.premium",
      "appUserId": "example_user_id",
      "subChangeState": "Rebuy",
      "stateChangeTime": 1593705685
    }
  

Note: In case want to get a deeper understanding of our API, feel free to check out the Web API documentation. The API is documented according to the openapi3.0 standard.

Done! Lean back and let Mage optimize in-app purchase prices

Once you are all set, Mage starts with analyzing your sales in all countries. To ensure 100% control, we implemented a confirmation process, which lets you have the final say. You have the choice if new prices will take effect. As soon as the first learnings can be drawn, the Mage optimization engine will generate recommendations for your in-app products. You will be notified, once new recommendations are waiting for your confirmation.

To see and take actions on your new recommendations, simply login into the Mage configuration portal. The “Recommendation” overview shows you all new recommendations, which were never denied or accepted. You can find more info about how our recommendations work in our Recommendations Management guide.

Note: Accepting recommendations will activate the new price for a product immediately for all new connecting devices. On an “app start” event, new prices will be fetched by the SDK for the app user.

Note: By neither accepting nor rejecting, you can postpone decisions. But be aware that with new recommendations, the postponed decision might be no longer available.