Quarters Unity SDK

Before you start
Getting Started
- Installation
- Setup
  - iOS
  - Android
Sample app
Unity supported versions
SDK supported platforms
SDK calls to API Reference
Troubleshooting

Before you start

In order to have a full integration with QuartersSDK you must follow this steps:

Register your APP following the steps in poq-docs.
It's mandatory to verify your app before your app can take Quarters from users. Please follow these steps:
1. Join our PoQ Game Devs discord server
2. Send us a message to our public channel 💡┋api-and-integration where we are going to handle your request.

Also if you want you can join Pocketful Of Quarters main discord server to be updated with the latest news and meet the rest of the community.

Getting Started

Installation

Open Unity package manager
Select "+" button and then Add the package from git repository (or if you have downloaded QuartersSDK Unity project you can import it from there selecting package.json inside quarters-unity-sdk-weiks\Packages\gg.poq.unity.sdk)

Enter the URL from poq-unity-package-manager project repository and press Add button. Unity Package Manager will pull Quarters Unity SDK and all of its dependencies to the project.
Add the following prefab to your first loaded scene Packages/Quarters Unity SDK/Runtime/QuartersSDK/Prefabs/QuartersInit

Press Open App Dashboard button. The web browser will open URL to create new Quarters app. Press Save button after populating the form.

Back in Unity QuartersInit component copy the values from app dashboard to the inpector tab of QuartersInit Component:
- APP_ID -> client_id
- APP_KEY -> client_secret
- APP_UNIQUE_IDENTIFIER -> It needs to be App URL sub-domain (ex. in this case exampleapp as in the image below)
  Please check the addiotional values you can set in the Unity inspector tab:
- Environment -> select Production if your app was registered in production apps environment otherwise select Sandbox.
- Default scope -> select the 5 scopes (Identity, Email, Transactions, Events and Wallet).
- Currency config -> set it in QuartersCurrency

Setup

For the best user experience, Quarters Unity SDK utilises domain association to link users back to the app after purchasing and authorisation. Quarters SDK manages browser to app linking automatically. To set up linking please follow the steps for the chosen platform

iOS

Open your PoQ APPS
Find your app and select iOS under the Auto Manage option
Enter any valid string as your PoQ app's unique identifier if empty
Enter Apple Team ID. It can be pulled from Apple account
Enter your app bundle id. Example com.mycompany.mygame
Press Submit
Copy your PoQ app's unique identifier to the QuartersInit component APP_UNIQUE_IDENTIFIER field in Unity and press Save

Android

Open your PoQ APPS
Find your app and select Android under the Auto Manage option
Enter any valid string as your PoQ app's unique identifier if empty
Enter your app package name. Example com.mycompany.mygame
You need to get SHA-256 certificate fingerprint, to do that just run the following command on your terminal (note the keytool comes with the Java SDK or included with Unity Android OpenJDK ex. C:\Program Files\Unity\Hub\Editor\2021.3.2f1\Editor\Data\PlaybackEngines\AndroidPlayer\OpenJDK\jre\bin in case of Unity 2021.3.2f1 editor)

keytool -list -v -keystore mystorekeystore.keystore

Running this command should yield something similar to the following image:

Press Submit
If you haven't already copy your PoQ app's unique identifier to the Quarter's Init component APP_UNIQUE_IDENTIFIER field in Unity and press Save

That's it you are ready to use Quarters Unity SDK

Sample app

Quarters Unity SDK contains a basic sample app presenting major SDK functionality like

Sign In with Quarters
Sign Out
Spend (Pay Quarters menu option): need to register your app manually contacting us on any channel as described in Before Start section. For this transaction you won't be able to use the same account that you used as a developer to register your app.
Receive (Receive Quarters menu option) Quarters. For this transaction you won't be able to use the same account that you used as a developer to register your app.
Buying (Buy Quarters menu option) Quarters through the website portal

To import the sample scene select Sample Import from Unity Package Manager

SamplePreview1.mov

Unity supported versions

Unity 2019.4+

SDK supported platforms

iOS
Android: API 29 and above
Unity Editor: due to limitations of Unity Editor on Windows external browser is used to authorize user you can check sign-in-with-quarters for details.

SDK calls to API Reference

In order to make all the operations/transactions with Quarters you will be able to interact with the SDK calls that consumes an API. See that calls fully documented with methods and examples in this README-Api file. Here we will list a quick review of the API operations:

Sign in with Quarters

Once QuartersInit is completed configured you will be able to sign in.

You will find the method to use and an example in fully documented SDK calls documentation .

Please note that due to limitations of Unity Editor on Windows external browser is used to authorize user. After successful authorisation please copy and paste the browser url to unity game view and press Authorize.

Making Transactions

You can charge user Quarters as well as reward your user with quarters using unified Transaction API call. A negative price takes Quarters from the user's account. Positive price value reward user account with Quarters

Please go to the SDK calls to API documentation for method description and a code example.

Buying Quarters

User can also purchase Quarters by using the credit card or other methods.

Please note that real money transactions are performed outside the application in the browser to adhere to Apple and Google's guidelines.

Please go to the SDK calls to API documentation for method description and a code example.

Sign Out

To sign out current Quarters users call.

Please go to the SDK calls to API documentation for method description and a code example.

Troubleshooting

⚠️ Important notes: ⚠️

Currently you cannot make a transfer between your app and your developer account. To test your app, you need to create a secondary test account on https://www.poq.gg/. For more information about transfers you can check our API documentation.

Pay or receive Quarters throws Transaction Error

When you try to Pay or receive Quarters you get Transaction Error: Debit and Cretit address cannot be the same. You cannot test your app when you are logged into your developer account to fix it:

Sign Out.
Sign In with a registered user that is has not developer rights.

Pay or receive Quarters throws Missing refresh token

When you try to Pay or receive Quarters you get Missing refresh token to fix it:

Sign Out.
Sign In again with the same account.

Pay throws Your app must be verified to transfer Quarters from users

When you try to Pay or receive Quarters you get Your app must be verified to transfer Quarters from users to fix it:

Verify your app contacting us.

Pressing `Authorize` in Android mobile doesn't redirect to the app.

When you Sign In with the sample app you are not redirected to the app after pressing Authorize button in your browser.

You need to:

A) Set your Android `manifest.xml` settings to open your app url

Open your Android manifest file and add these lines to enable the link redirection option in your app:

   <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="https" android:host="#YOUR_APP_LINK.games.poq.gg" android:pathPattern=".*" />
      </intent-filter>

If your manifest already had these lines, skip to step B if that was not the case, save your manifest and build your app to generate the new installer that you will use for steps B and C.

B) Set your Android default browser to Chrome

Some mobile internet browsers (like Samsung default browser) don't redirect to the app inmediatly. In case you want to be redirected inmediatly to the app change your default internet mobile browser:

On your Android phone, tap Settings.
Then tap Apps & Notifications (or in old Android versions App Management) and finally Default Apps
There on the option Browser App you will be able to change your default mobile browser

C) Enable support to web addresses in your app

On your Android phone, tap Settings.
Then tap Apps & Notifications (or in old Android versions App Management) Default Apps/Openning links
Choose your app (ex Quarters SDK) there you will be able to enable Open supported links.
Open Supported web links to check that the link of your app is in that list.

You can follow the steps in this video:

PoQ-Enable.supported.links.-.Made.with.Clipchamp.mp4

If after performing steps A, B and C the problem persists, please read the following troubleshooting case Still not redirecting to the app after pressing the Authorize button

Still not redirecting to the app after pressing the `Authorize` button.

Besides trying the steps in "Pressing Authorize in Android mobile doesn't redirect to the app" the issue still happens please contact us.

PoQ dev team decided not to create a possible solution because it would apply to an end user and all the alternatives could expose them to phishing. For example lets suppose this case where you set up a game called Original Authorized game:

You verified it and has access to user's wallets.
Published it to App Store and Google Play.
Another app realizes that anyone can just get the troubleshooting link with validation code (generated by us for this issue) and paste it into any app, so they reuse the same link as your game (because they easily can, it's a public link).
Then when the user is redirected back and since your real Original Authorized game is not installed nothing opens and it shows the link with the code, whether encrypted or not.
User then goes to the fake app and pastes the code
The fake app calls our API with the code and gets an access token on behalf of Original Authorized game.
The fake app can do whatever Original Authorized game can do without any restrictions, and as PoQ we can't stop them.

Making a transaction (pay or receive) shows `Transaction error: Debit and credit address cannot be the same.`

When you create an app with your developer account supposse [email protected] you login to the integration app using that developer account if you try to make a transaction (as long as it's pay or receive) you will get this message error:

To fix it:

Log out from the integration app.
Login to the integration app with a different account than the one you used to create the app ([email protected]).

gonzalovelasco / quarters-unity-sdk Goto Github PK