Paywalls v2 docs [New Categories]

docs/tools/paywalls-v2.mdx

@@ -0,0 +1,55 @@
+---
+title: Paywalls v2
+slug: paywalls-v2
+hidden: false
+---
+
+RevenueCat's Paywalls allow you to remotely configure your entire paywall view without any code changes or app updates. Whether you're building a new app, exploring new paywall concepts, or diving into experimentation; RevenueCat's Paywalls make it easy to get started.
+
+And now, Paywalls v2 has been built from the ground up to allow you to build fully customizable layouts from underlying components, and its available in beta on iOS.
+
+import YouTubeEmbed from "@site/src/components/YouTubeEmbed";
+
+<YouTubeEmbed videoId="Mp9EymiJ0F0" title="RevenueCat Paywalls v2 Beta" />
+
+:::warning Beta Limitations
+Paywalls v2 is currently in beta, and has the following limitations:
+
+1. Only available on our Native iOS SDK, on versions 5.16.0+. **You must update your RevenueCat SDK to use paywalls built with the new editor.**
+2. Not supported on watchOS, or visionOS.
+3. Footer mode from our original templates is not supported, [learn more here](/tools/paywalls-v2/displaying-paywalls).
+   :::
+
+You can think of a Paywall as an optional feature of your Offering. An Offering is the collection of Products which are organized into Packages to be displayed to your customers as a single "offer" across platforms. Now, with Paywalls, you can control the actual view that is used to display that "offer" in addition to controlling the products that are offered.
+
+Therefore, you can create a unique Paywall for each of your Offerings, and can create an unlimited number of Offerings & Paywalls for each variation you want to test with Experiments.
+
+### Getting Started
+
+Our paywalls use native code to deliver smooth, intuitive experiences to your customers when you're ready to deliver them an Offering; and you can use our Dashboard to build your paywall from any of our existing templates, or start from scratch to create your own. Either way, you'll have full control of the components and their properties to modify the paywall to meet your needs.
+
+To use RevenueCat Paywalls v2, simply:
+
+1. [Install the RevenueCat UI SDK](/tools/paywalls-v2/installation)
+
+2. [Create a Paywall](/tools/paywalls-v2/creating-paywalls) on the Dashboard for the [Offering](/getting-started/entitlements) you intend to serve to your customers
+
+3. See [displaying paywalls](/tools/paywalls-v2/displaying-paywalls) for how to display it into your app.
+
+## Limitations
+
+### Platforms (support for more coming)
+
+- ✅ iOS 15.0 and higher
+- ❌ Android (coming soon)
+- ❌ Mac Catalyst
+- ❌ visionOS
+- ❌ watchOS
+- ❌ macOS
+- ❌ tvOS
+
+## Next Steps
+
+- Now that you know how our paywalls work, read about [creating paywalls](/tools/paywalls-v2/creating-paywalls)
+- Once you're ready to see your paywalls in action, you can follow our guides on [displaying paywalls](/tools/paywalls-v2/displaying-paywalls)
+- If you need inspiration with some paywall examples, you can try our [Paywalls Tester app](https://github.com/RevenueCat/purchases-ios/tree/main/Tests/TestingApps/PaywallsTester)

docs/tools/paywalls-v2/creating-paywalls.mdx

@@ -0,0 +1,135 @@
+---
+title: Creating Paywalls
+slug: creating-paywalls
+hidden: false
+---
+
+Use the brand new Paywall Editor to design a fully customizable paywall.
+
+:::warning Beta Limitations
+Paywalls v2 is currently in beta, and has the following limitations:
+
+1. Only available on our Native iOS SDK, on versions 5.16.0+. **You must update your RevenueCat SDK to use paywalls built with the new editor.**
+2. Not supported on watchOS, or visionOS.
+3. Footer mode from our original templates is not supported, [learn more here](/tools/paywalls-v2/displaying-paywalls).
+   :::
+
+import YouTubeEmbed from "@site/src/components/YouTubeEmbed";
+
+<YouTubeEmbed
+  videoId="vE17MFOv6Qc"
+  title="RevenueCat Paywalls v2 Walkthrough"
+/>
+
+## Key concepts
+
+| Concept              | Description                                                                                                                       |
+| :------------------- | :-------------------------------------------------------------------------------------------------------------------------------- |
+| Components           | RevenueCat's predefined UI elements that can be added to a paywall. (e.g. text, an image, a purchase button, etc.)                |
+| Component properties | The properties of each component that can be configured to modify it's style and behavior. (e.g. its width, height, border, etc.) |
+| Templates            | The paywalls that RevenueCat has already created that you can use as a starting point to build your own paywall from.             |
+
+## Components
+
+Components are the individual building blocks of your paywall that can be arranged and configured to create your own custom layout.
+
+| Component       | Description                                                                                |
+| :-------------- | :----------------------------------------------------------------------------------------- |
+| Text            | Used to add customizable text strings                                                      |
+| Image           | Used to add an uploaded image                                                              |
+| Icon            | Used to add a customizable icon from our provided list                                     |
+| Stack           | Used as a parent component to jointly configure its child components                       |
+| Package         | Used to add a selectable package with custom styling, text, etc.                           |
+| Purchase button | The call to action that invokes a purchase attempt of the selected package.                |
+| Button          | Used to add other interactions; such as a link to your Privacy Policy, a back button, etc. |
+| Footer          | A configurable portion of your paywall whose position is fixed and uniquely styled.        |
+
+:::info Parent components
+Stacks, packages, buttons, and the footer are all parents components which can contain other child components within them to be jointly controlled.
+:::
+
+[Learn more about each component.](/tools/paywalls-v2/creating-paywalls/components)
+
+## Building paywalls
+
+To get started building paywalls with our new editor, click on **+ New Paywall** in the callout on the Paywalls page for your Project:
+
+![Create new paywall](/images/paywalls-create-new-paywall.png)
+
+Next, you'll need to select the Offering you want to add a Paywall to. Or, if you don't have any Offerings without Paywalls, you'll have the option to duplicate an existing one or create a new one.
+
+From there, you can start building by either:
+
+1. Choosing a template, or
+2. Starting from scratch
+
+Unless you have a very specific, custom design in mind that you're looking to create; **we recommend starting with a template.** You can customize any aspect of your paywall once you select a template, it's simply a starting point to explore from.
+
+![Select a template](/images/paywalls-select-template.png)
+
+### Using the editor
+
+Once you've selected a template or picked starting from scratch, you'll land on our Paywall Editor, which has the following sections:
+
+1. **Components**: The list of components on your paywall, their hierarchy, and their options (rename, duplicate, etc).
+2. **Component properties**: The list of configurable properties of the component you've selected.
+3. **Preview**: The preview of your paywall.
+4. **Control panel**: The options to change the locale, light/dark mode, and other preview settings to see how your paywall looks in various scenarios. The control panel is also where you can manage localizations through one page instead of modifying them component-by-component.
+
+![Paywalls editor](/images/paywalls-editor.png)
+
+### Adding components
+
+Components can be added to a paywall in two ways:
+
+1. Directly to the main paywall with the **+ Add Component** button
+2. Directly within a parent component, such as a stack, with the **+** button in that component's row in the components panel.
+
+Once a component has been added to a paywall, you can determine its order on your paywall by dragging it vertically in the stack, or determine its parent component by dragging it underneath the desired parent and indenting it horizontally.
+
+![Arrange components](/images/paywalls-arrange-components.gif)
+
+:::tip Parent & child components
+A child component will be subject to the axis, alignment, distribution, and child spacing properties of the parent component; and will be impacted by other properties such as margin & padding.
+:::
+
+### Modifying components
+
+When you click on a component in the components panel, you'll see it displayed in the component properties panel on the right side of your screen. These properties represent the configurable elements of each component that can be used to give it a unique look and feel.
+
+Many properties for controlling layout, size, and appearance are similar between components; but each one has their own unique properties that are specific to the use cases of that component.
+
+[Learn more about component properties.](/tools/paywalls-v2/creating-paywalls/component-properties)
+
+![Stack properties](/images/paywalls-stack-properties.png)
+
+In addition, by clicking on the **...** option in a component's row in the components panel, you can rename, duplicate, or delete any component.
+
+![Stack options](/images/paywalls-stack-options.png)
+
+### Saving a paywall
+
+When saving a paywall, there are two different states it can be saved in depending on what you're ready to do with it.
+
+| Paywall State | Description                                                                                                                                                                                                                                                                               |
+| :------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Inactive      | Paywalls that you do not wish to serve to customers. You can think of these as drafts, or works in progress. Inactive Paywalls will not be available through the SDK.                                                                                                                     |
+| Published     | Paywalls that you may wish to serve to customers. These will always be returned on supported SDK versions. Whether they will be served to customers depends on whether you've configured the associated Offering as the Default Offering, or are serving it via Targeting or Experiments. |
+
+When creating a new paywall, you can save your changes at any time by clicking the **Save Changes** button at the top right of the page.
+
+This will save your paywall in an inactive state so that you can continue editing it, but it will not yet be sent to your app and made available to customers.
+
+To make your paywall available to customers, click **Publish Paywall**. Once a paywall is published, it will be available via the RevenueCat SDK and therefore can be seen by your customers depending on how you're serving Offerings to them.
+
+You can also set a published paywall to be inactive, or vice versa, at any time.
+
+:::tip Required components
+All paywalls must have a purchase button and at least one package added in order to be publishable.
+:::
+
+:::warning Minimum supported SDK version
+Paywalls built through the new v2 paywall editor are only supported on RevenueCat Native iOS SDK versions 5.16.0+ or later. If you have existing app version serving RevenueCat Paywalls, setup a [Targeting Rule](/tools/targeting) to continue serving them a v1 paywall, so that only customers on supported app versions are served a new v2 paywall.
+:::
+
+[Learn more about displaying paywalls.](/tools/paywalls-v2/displaying-paywalls)

docs/tools/paywalls-v2/creating-paywalls/app-review.mdx

@@ -0,0 +1,31 @@
+---
+title: Getting your paywall approved through app review
+slug: app-review
+hidden: false
+---
+
+Paywalls are frequently one of the most scrutinized areas of your app in App Store and Play Store review, since the stores want to ensure apps are setting clear expectations about what’s being offered to customers. Below are some of the most common rejection reasons, and how you can best position yourself to avoid them with RevenueCat Paywalls:
+
+**Full billed amount is not clearly shown**
+Though it can be useful to show the relative value of one option over another by comparing the two with a common duration (e.g. normalizing your $49.99/yr subscription to the equivalent of $4.16/mo), it’s important that the full billed amount ($49.99/yr) is clearly provided on your paywall.
+
+You can provide this using variables like `product.price_per_period` / `product.price_per_period_abbreviated` depending on your preferred format.
+
+However, other variables like `product.price_per_month` or `product.price` on their own may not satisfy this requirement unless your paywall clearly states the full billed amount and recurrence in some other way.
+
+**Introductory offer is not clearly shown**
+Similar to the full billed amount, if the nature of the introductory offer is not clear enough on your paywall, your app may also get rejected for that reason, since this is what the customer is about to receive (and potentially pay for) immediately upon converting.
+
+To address this with RevenueCat Paywalls, consider using `product.offer_price` and `product.offer_period` in either your package details or your CTA to ensure that the introductory offer is clearly disclosed.
+
+:::info
+India has particularly strict rules regarding the disclosure of offer terms, and you may find that your paywall is more likely to get rejected for that reason if its offered in India.
+:::
+
+**The opportunity to cancel is not clearly disclosed**
+In addition, in some cases the store will look for explicit language around the fact that customers can cancel their subscription, as well as how they might do that; so considering adding these notes if you want to be sure to avoid a rejection for that reason. (e.g. "Try free for x days, then $y/mo. Cancel anytime.")
+
+**Missing terms & conditions or missing privacy policy**
+Though the App Store in particular no longer requires these policies to be accessible directly from your paywall, they do still require that they are accessible _somewhere_ in your app, and the paywall is a common place for them to be.
+
+If either the terms & conditions or the privacy policy of your app is missing, or just too difficult to find in the reviewer's opinion, your app may be rejected for that. To prevent this, try providing the terms & privacy policy on your paywall through RevenueCat Paywalls so they'll be easy for your customers and for app reviewers to find.

docs/tools/paywalls-v2/creating-paywalls/component-properties.mdx

@@ -0,0 +1,71 @@
+---
+title: Component Properties
+slug: component-properties
+hidden: false
+---
+
+# Component properties
+
+Paywalls are made up of individual components that you add and arrange, and those components each have their own properties to be configured that define how it looks and behaves.
+
+## Position properties
+
+:::info Parent components only
+Position properties only apply to parent components, since they control how the child components are arranged relative to one another.
+:::
+
+A parent component's **axis** controls whether its child components are arranged horizontally, vertically, or three-dimensionally.
+
+**Alignment** determines how components are arranged against that axis; such as top, center, or bottom aligned elements across a horizontal axis.
+
+![Axis and alignment](/images/paywalls-axis-alignment.gif)
+
+**Distribution** determines how components are spaced along the defined axis.
+
+Last, **child spacing** determines exactly how much space should be set between each child component.
+
+![Distribution](/images/paywalls-distribution.gif)
+
+## Size properties
+
+Each component's **width** and **height** can be sized to:
+
+1. Fit the space needed for the content
+2. Fill the available space for the component
+3. Occupy a fixed space
+
+## Layout properties
+
+Each component's spacing can be configured through **margin** (added space outside of the component to create distance from adjacent components) and **padding** (added space within the component to create distance between the content and the edge of the component).
+
+By default, you can configure each value uniquely, or you can click on the icon to the right of the property to switch to configuring horizontal and vertical margin and padding simultaneously,
+
+![Layout](/images/paywalls-layout-settings.gif)
+
+## Appearance properties
+
+Each component may have a configurable **background color**, which can be a solid color or a gradient, and may have a specified opacity level.
+
+A component's **shape** can additionally be configured to select between rectangle and pill.
+
+Last, if the rectangle shape is used, then its **corner radius** can also be configured.
+
+## Border properties
+
+Parent components can additionally have a specified **border color** and **border width** to create visual separation between them and other components.
+
+## Drop shadow
+
+Parent components can have a drop shadow configured for them via a customizable **position** (x and y axis offset), **blur** (size of the shadow effect), and **color**.
+
+## Badge
+
+Parent components can have badges configured for them that can be used to easily append an element on top of the component that has its own text and appearance. Badges are most frequently used to callout package discounts, special offers, etc, but can also be configured for other use cases you have in mind.
+
+Badges can be configured in either a **nested** or **overlaid** style. Nested badges on the inside border of parent component they're added to, while overlaid badges are centered on top of the border.
+
+The exact position on the border is determined by the **axis** of that badge, as well as any additional margin you add to adjust its position along that axis.
+
+![Badge properties](/images/paywalls-badge-properties.png)
+
+Badges can additionally have their own text styling, border, and drop shadow so they have a unique look and feel to draw a customer's attention to them.