> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.qonversion.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Unity 4.+ migration guide

## Upgrading version

Increase the dependency version in your Packages/manifest.json file to upgrade your Qonversion SDK to the latest

<CodeGroup>
  ```json manifest.json theme={null}
  "com.qonversion.unity": "https://github.com/qonversion/unity-sdk.git#4.0.0"
  ```
</CodeGroup>

## Initialization

Qonversion Unity SDK 4 contains significant changes in how the library is initialized. We are moving from a static class approach to an instance-based one. Before, you initialized Qonversion using the `Launch` call:

<CodeGroup>
  ```csharp Unity theme={null}
  Qonversion.Launch("projectKey", true);
  ```
</CodeGroup>

Now, instead, you should create a `QonversionConfig` object using `QonversionConfigBuilder` and provide it to the initialization method as follows:

<CodeGroup>
  ```csharp Unity theme={null}
  QonversionConfig config = new QonversionConfigBuilder(
          "projectKey",
          LaunchMode.SubscriptionManagement
      ).Build();
  Qonversion.Initialize(config);
  ```
</CodeGroup>

Note that instead of providing the `observeMode` flag to the `Launch` call, you now should provide a concrete value from the `LaunchMode` enum depending on which mode you use Qonversion. Also, we've renamed our modes to make them more transparent for users:

* "Observe" mode becomes "Analytics" mode,
* "Infrastructure" mode becomes "Subscription Management" mode.

After the initialization, you can access the Qonversion instance whenever you want as follows:

<CodeGroup>
  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance();
  ```
</CodeGroup>

So you should replace all your Qonversion calls with the construction above.

Also, if you were using `Qonversion.SetDebugMode()` for testing purposes, you should now call the `SetEnvironment(Environment.Sandbox)` method of the `QonversionConfigBuilder`.

## Entitlements

We are on the way to renaming permissions to entitlements as this naming suits more what it is used for. So, the following objects and methods were renamed in this release:

| Version \<4                | Version 4+                    |
| -------------------------- | ----------------------------- |
| Permission                 | Entitlement                   |
| QProductRenewState         | QEntitlementRenewState        |
| QPermissionSource          | QEntitlementSource            |
| PermissionsCacheLifetime   | EntitlementsCacheLifetime     |
| CheckPermissions           | CheckEntitlements             |
| OnPermissionsReceived      | OnEntitlementsReceived        |
| OnUpdatedPurchasesReceived | OnUpdatedEntitlementsReceived |
| UpdatedPurchasesReceived   | UpdatedEntitlementsReceived   |

The `Entitlement` class contains the same information as the `Permission` with a renaming of the `PermissionID` field - now it's named simply `Id`.

There is no `SetPermissionsCacheLifetime` method in Qonversion. You should provide `EntitlementsCacheLifetime` to `QonversionConfigBuilder` during the initialization using the `SetEntitlementsCacheLifetime` method.

<CodeGroup>
  ```csharp Unity theme={null}
  QonversionConfig config = new QonversionConfigBuilder(
          "projectKey",
          LaunchMode.SubscriptionManagement
      )
      .SetEntitlementsCacheLifetime(EntitlementsCacheLifetime.Year)
      .Build();
  Qonversion.Initialize(config);
  ```
</CodeGroup>

## Automation changes

We've also changed the way the `Automations` is used. As in Qonversion, you should use `Automations` via the shared instance. On the first access, it will be initialized and returned. Then the initialized instance will be used.

<Info>
  You should access the shared instance of `Automations` strictly after you initialize Qonversion, else an exception will be thrown.
</Info>

<CodeGroup>
  ```csharp Unity theme={null}
  QonversionConfig config = new QonversionConfigBuilder(
          "projectKey",
          LaunchMode.SubscriptionManagement
      ).Build();
  Qonversion.Initialize(config);
  Automations.GetSharedInstance().SetDelegate(...);
  ```
</CodeGroup>

Also, the methods for working with push notifications were moved from `Qonversion` to `Automations`, so if you were using the following methods:

* `SetNotificationsToken`,
* `HandleNotification`,
* `GetNotificationCustomPayload`, make sure to make calls from the Automations instance instead of the Qonversion one.

## Rest of the changes

Along with the changes described above, there are several technical improvements and other changes in the new major release:

* all the internal classes were moved to the `Internal` package, and DTO classes were moved to the `Dto` package to make the library file structure more readable;
* the deprecated methods `SetUserID` and `Purchase` methods with `OnPermissionsReceived` callbacks were removed. `SetUserID` should be replaced with the `setProperty` call with the `UserProperty.CustomUserId` parameter.
* added the new method `UserInfo`, which returns the information about the current Qonversion user. Now it contains internal Qonversion and identity identifiers. The user info may be extended in future releases;
* added new enum values - `QOfferingTag.Unknown` and `QTrialDuration.Unknown`, which are used when parsing fails;
* the `EntitlementsCacheLifetime` enum values were rewritten in UpperCamelCase to meet the rest enums style;
* added new values `AppleSearchAds` and `AppleAdServices` to the `AttributionProvider` enum,
* the following methods, classes, and values renamings took place:

| Old name                                  | New name                           |
| ----------------------------------------- | ---------------------------------- |
| `AddAttributionData`                      | `Attribution`                      |
| `CheckTrialIntroEligibilityForProductIds` | `CheckTrialIntroEligibility`       |
| `SetAdvertisingID`                        | `CollectAdvertisingId`             |
| `SetAppleSearchAdsAttributionEnabled`     | `CollectAppleSearchAdsAttribution` |
| `AttributionSource`                       | `AttributionProvider`              |

***

[React Native 4.+ migration guide](react-native-4-migration-guide)

[AI-Ready: Visit our llms.txt file](llmtxt)