Understanding Rules in Apphud

UPDATE. Since the publication of the article Rules has been significantly improved in Apphud. Now we support scheduled and manual push campaigns, allowing you to run campaigns whenever you want to your custom audience.

Apphud may help to win back churned subscribers, reduce churn rate, get cancellation insights, reduce involuntary churn, and many more using the mechanics below. These mechanics are called Rules.

Currently, rules are supported only in iOS. Android support will be added later.

Rules in Apphud 

When creating a new rule you will need to choose a rule type. The most popular ones are Get cancellation insights and Win back lost subscribers. Let's take a closer look at these.

Creating each Rule type itself doesn't have any differences except choosing a Screen. While creating the Get cancellation insights rule you will need to create a survey screen. The default question in this survey screen is "Why did you cancel subscription?". While creating the Win back lost subscribers rule you can choose paywall screens only.

You can choose an event at which the rule will be triggered. By default, it's "Autorenew disabled", which is being called when subscription auto-renewal is turned off in subscriptions settings in App Store.

"When to perform rule" Apphud

Currently, "Autorenew disabled" is deprecated, but Rules will continue to work correctly. There are two new events that replace this event: "Trial canceled" and "Subscription canceled". The first one is being created when users cancel a free trial subscription, in other cases "Subscription canceled" event is created.

Trial canceled event is also created when canceling a free trial purchased from a promotional offer or Offer Code (available since iOS 14). Trial Canceled is also created when a grace or expired subscription was canceled automatically due to an unrecovered billing issue if the subscription wasn't paid.

You can also choose other events, like, "Subscription expired". In this case, a rule will be triggered when the paid subscription period is actually expired.

At the question "How many times rule can be performed for each user?" you can choose "unlimited times". It means that if a user cancels the subscription again, the same rule will be triggered and a new push notification will arrive.

At the "User segments" section you can choose your audience to which your Rule will be applied. The following segments are available:

• Subscription status – a current status for a subscription for a certain product group;
• Autorenewal – whether auto-renew is turned on or not;
  
• Is paying – true, if a user is (or was) paying customer;
  
• Country – user's country;
  
• Install month – app install month.

Add User segment

At the "Actions" section you can set Push notification title and message, which can be localized. In order to add localization, you must first add it in Apphud -> iOS localization

Also here you select a screen, which will be shown in the app.

Show localized push notifications

When the user cancels the subscription, Apple sends a server notification to Apphud with notification_type = DID_CHANGE_RENEWAL_STATUS. In this notification, there is also a receipt snapshot, which is a JSON format string with an in-app receipts array. There is original_transaction_id – the unique subscription identifier. Using this identifier Apphud finds a customer in its database and if found, triggers a rule with push notification.

To receive server notifications from Apple, you must set the URL for App Store Server Notifications. More details here.

Once a user opened Push notification, Apphud SDK loads and displays a modal screen with whatever the user has configured. If a user didn't open Push notification, a screen will still be displayed at the next app launch or activation.

When executing Rules, Apphud sends a Push notification to a user, if they have a device token.

• Please make sure that you correctly send device tokens to Apphud using the method below: func submitPushNotificationsToken(token: Data, callback: ApphudBoolCallback?)
• Then make sure that incoming push notifications are also handled: func handlePushNotification(apsInfo: \[AnyHashable: Any\]) -> Bool
  
•  And check that APNS Auth Key is created and uploaded to Apphud. More details here.

You can create and edit your screens over-the-air using a powerful web editor. When creating a new screen you can choose one of four types: Promo offer (Paywall), Survey, Feedback, and Billing Issue.

Screens Editor has many great features:

• Choose between ready templates and edit style: color, font, etc;
• Change background images on your own;
  
• Screens localization;
  
• Show another screen on button tap. The next screen will be pushed in the navigation controller hierarchy;
  
• Macroses which replace product prices;
  
• Hide blocks you don't need.
  
• Many options to control behavior in the app-level using ApphudUIDelegate.
  

You can set your own survey text and answer options. For each answer option, you can present another screen, like one more survey or promo offer screen.

Survey text and answer options

Paywall screens can be of two types: with or without promotion offers. This option can be configured in the Purchase button section. When creating a paywall screen you must provide Product ID, and optionally Promo Offer ID if purchasing a promotional offer.

Promotional Offers

When choosing Purchase promo offer on tap, you must provide a promotional offer identifier, that is being set in App Store Connect when creating a promotional offer for a subscription product.

Don't get confused with Offer Codes!

Keep in mind, that purchasing subscription offers requires generating a signature using Subscription Key. Luckily, Apphud handles that from the box. You just need to create Subscription Key in App Store Connect and upload it to Apphud. You can read more about generating subscription key here.

Promotional offer

Set promotional offer id and product id:

Choose Product id

Regular in-app purchase

When you choose Purchase product on tap, it means purchasing a regular subscription or in-app purchase. Promotional offer id should be left blank.

Actions on tap

If the user wants to close the screen, you can also present another screen, so that the new screen will be pushed into the navigation controller hierarchy. For example, you can offer a better discount when the user wants to close the paywall.

Localised in-app purchase price

In order to display the localized prices for IAP, you can use macroses – orange buttons near to text fields.

Use macroses

Macroses can be of two types: Regular or Offer price.

Macros: Regular Price

This is the regular price of your in-app purchase, just select Product ID and Apphud SDK will automatically replace macros with the standard product price.

Macros: Offer Price

This is a promotional offer price, you should set Promo Offer ID and Product ID, the same values that in the Purchase button. Apphud SDK will automatically replace this macros with promotional offer price.

If you use a free trial period, you can add your own text and combine it with macros. For example: 3 days for free, then just {regular_price} per month.

Phrases "3 days for free, then just" and "per month" you add manually, and regular price is replaced by SDK.

Information Block

By default, the long text with subscription information is shown in this block. You can edit the text or remove this block at all – it is not required anymore.

Many blocks can be hidden with the "Hide block" button.

Hide Block button for info text

Apphud SDK has many ways to control rules behavior. Here are some:

• Override rule execution and return false to cancel rule execution. Using this delegate method you can present your own screens. Keep in mind, that in this case Rule Analytics will not work: func apphudShouldPerformRule(rule: ApphudRule) -> Bool
• You can override dismiss an action for Feedback or Survey screen types. By returning the none value, you can cancel automatic screen dismissal and push your own controller into the hierarchy by using navigationController property of controller: func apphudScreenDismissAction(screenName: String, controller: UIViewController) -> ApphudScreenDismissAction
• See ApphudUIDelegate for more details
• Update Apphud SDK to version 1.2 or higher, it has significant improvements in Rules and Screens
  

To display Apphud Screens in the app, you need to create a Rule, a Screen, and set up push notifications.

• Everything can be handled over-the-air except handling push notifications.
• Please make sure that you correctly send device tokens to Apphud using the method below: func submitPushNotificationsToken(token: Data, callback: ApphudBoolCallback?)
  
•  Then make sure that the incoming push notifications method is also being called func handlePushNotification(apsInfo: [AnyHashable: Any]) -> Bool
• Make sure you created and uploaded APNS Auth Key. Test your Rule implementation. In Apphud Rules section, click on "Test Rule", enter your Apphud User ID and view results.
  
• By default, screens are presented modally using modern way (not fullscreen). You can change this using the following delegate method: func apphudScreenPresentationStyle(controller: UIViewController) -> UIModalPresentationStyle
  
• For purchasing promotional offers, you need to create a promotional offer for your subscription in App Store Connect, and set a promo offer identifier in Apphud Screen Editor. Generating and uploading Subscription offer key is also required.
  
• You can offer regular in-app purchases in Apphud Paywall Screens.
  
• Update Apphud iOS SDK to the latest version (1.2).
  

Ren

Co-founder at Apphud

Ex iOS app and game developer. 11 years in the industry since iOS 3. More than 50 apps are in the background with 4 exits. Entrepreneur and traveler.