[EXTERNAL] Add ExperimentalPreviewRevenueCatPurchasesAPI opt-in requirement to Purchases.awaitCustomerInfo()

[pablo-guardiola]

Checklist

• If applicable, unit tests
• If applicable, create follow-up issues for purchases-ios and hybrids

Motivation

Why is this change required? What problem does it solve?

Follow up from https://github.com/RevenueCat/purchases-android/pull/1012/files#r1223917692

Instead of only noting that Purchases.awaitCustomerInfo() is experimental in the docs (which are often overlooked 😬), we can be more explicit and add an opt-in requirement annotation ExperimentalPreviewRevenueCatPurchasesAPI.

Capturing from the Kotlin Opt-in requirements docs:

The Kotlin standard library provides a mechanism for requiring and giving explicit consent for using certain elements of APIs. This mechanism lets library developers inform users of their APIs about specific conditions that require opt-in, for example, if an API is in the experimental state and is likely to change in the future.

To prevent potential issues, the compiler warns users of such APIs about these conditions and requires them to opt in before using the API.

This opens the door to use this annotation in any other APIs which are experimental, in preview or under cooking, to get initial feedback and iterate "without" breaking SemVer 🚀

Description

Describe your changes in detail

• Create ExperimentalPreviewRevenueCatPurchasesAPI opt-in requirement annotation
• Opt in to using ExperimentalPreviewRevenueCatPurchasesAPI wherever Purchases.awaitCustomerInfo() is called

Please describe in detail how you tested your changes

• Run purchases tests
• Run examples.purchase-test app

cc @tonidero @vegaro

[vegaro]

Thanks for opening. I think this makes a lot of sense to me. What do you think @tonidero

[vegaro]

Is ExperimentalCoroutinesApi needed?

[pablo-guardiola]

Yeah, it's needed to remove the runTest warning:

This declaration needs opt-in. Its usage should be marked with '@kotlinx.coroutines.ExperimentalCoroutinesApi' or '@OptIn(kotlinx.coroutines.ExperimentalCoroutinesApi::class)'

@MustBeDocumented
@Retention(value = AnnotationRetention.BINARY)
@Target(
    AnnotationTarget.CLASS,
    AnnotationTarget.ANNOTATION_CLASS,
    AnnotationTarget.PROPERTY,
    AnnotationTarget.FIELD,
    AnnotationTarget.LOCAL_VARIABLE,
    AnnotationTarget.VALUE_PARAMETER,
    AnnotationTarget.CONSTRUCTOR,
    AnnotationTarget.FUNCTION,
    AnnotationTarget.PROPERTY_GETTER,
    AnnotationTarget.PROPERTY_SETTER,
    AnnotationTarget.TYPEALIAS
)
@RequiresOptIn(level = RequiresOptIn.Level.WARNING)
public annotation class ExperimentalCoroutinesApi

I can remove it if you prefer so, as it's not mandatory.

[vegaro]

Interesting, because I get that message (This declaration needs opt-in...) in the annotation itself not in the runTest, that's why I am confused

[pablo-guardiola]

That @OptIn warning is different 👀

BTW note that what you're seeing are the docs from @ExperimentalCoroutinesApi that's not the warning you get if you don't add the @OptIn, if you remove it you should get it (followed by the docs) 👀

[vegaro]

I am seeing it today, but I didn't yesterday! Weird, I was very confused 😆

Thanks for taking the time taking screenshots and explaining

[pablo-guardiola]

Gradle...

[tonidero]

Yeah I think this makes sense. We probably won't get many users if they need to use this annotation, but if the API is subject to change, that's how it should be 👍

[pablo-guardiola]

We probably won't get many users if they need to use this annotation

You know that we developers love to live on the edge 🔥 😅

Jokes aside, I believe a bunch of customers will start using it (especially the ones that already use / integrate Coroutines in their codebase / apps) and we can start gathering feedback 🚀

[tonidero]

Yeah, in any case I think this is a good addition 👍