Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: link readme to official docs #39

Merged
merged 2 commits into from
Nov 15, 2023
Merged

docs: link readme to official docs #39

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9742b34
docs: link readme to official docs
nattb8 Nov 8, 2023
1963682
docs: fix broken link
nattb8 Nov 9, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file removed ImxBatchNftTransfer.png
View file
Open in desktop
Binary file not shown.
Binary file removed ImxTransferFlow.png
View file
Open in desktop
Binary file not shown.
Binary file removed PassportLoginFlow.jpg
View file
Open in desktop
Binary file not shown.
Binary file removed PassportLogoutFlow.jpg
View file
Open in desktop
Binary file not shown.
Binary file removed PassportPKCELoginFlow.png
View file
Open in desktop
Binary file not shown.
194 changes: 4 additions & 190 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,196 +10,10 @@

# Immutable SDK for Unreal Engine

## User Guide
# Documentation

### Supported Platforms

- Windows 10 (64-bit)
- macOS (minimum version 10.5)
- Android (minimum version 8.0)
- iOS (minimum version 13.0)

### Supported Unreal Engine Versions

- Unreal Engine 5.0 and above
- Unreal Engine 4.26 and above

## Registering your game

Before using Passport, you must register your application as an OAuth 2.0 **Native** client in the [Immutable Developer Hub](https://hub.immutable.com). First, you'll need to create a project and a testnet environment.
Then, you can navigate to the Passport config screen and create a passport client for your created environment.
When you're ready to launch your application on the mainnet, please ensure you configure a passport client under a mainnet environment. Here's how you can configure the fields while creating a client:

### Creating an OAuth2.0 Native client

#### Application Type
You must register your application as an OAuth 2.0 **Native** client.

#### Client name
The name you wish to use to identify your application.

#### Logout URLs
Native clients don't make use of Logout URLs, you might set your own site or https://localhost:3000 as this is a required field.

#### Callback URLs
On Android, iOS and macOS clients, you should set your application's deep link scheme (e.g. `mygame://callback`) if you wish to make use of [PKCE login](#android-and-ios-pkce-login-unreal-engine-50-only), otherwise set the same as [Logout URLs](#logout-urls).

[PKCE login](#android-and-ios-pkce-login-unreal-engine-50-only) is not supported on Windows clients. Hence, they do not use Callback URLs. You may set Callback URLs to be the same as [Logout URLs](#logout-urls), as it is a required field.

#### Web Origins URLs
Optional field. The URLs that are allowed to request authorisation. This field is available when you select the Native application type.

See [here](https://docs.immutable.com/docs/x/passport/register-application/) for more details.


### Installation

> :clipboard: Prerequisites
>
>[git-lfs](https://git-lfs.github.com/): since `.uasset` and `.umap` files are stored on Git Large File Storage, ensure you have [git-lfs]((https://git-lfs.github.com/)) installed.

1. Clone the [unreal-immutable-sdk](https://github.com/immutable/unreal-immutable-sdk) repository or download the zip/tarball from one of the versions [here](https://github.com/immutable/unreal-immutable-sdk/tags)
2. Copy the cloned repository into your project's `Plugins` folder, e.g.: `MyGame/Plugins/unreal-immutable-sdk`.
3. Restart your project (Unreal Editor & Rider), upon restart it should load the `unreal-sdk-plugin` and should be good to use.

> [!NOTE]
> For Unreal Engine 4.26 and above we use Blui as a browser instead of inbuilt browser. For Unreal Engine 5.0 and above we use inbuilt browser
> For UE4 only download the Blui Plugin from https://github.com/immutable/unreal-immutable-sdk/releases/download/0.1.1/BLUI.4.2.BluBrowserCEF.90.0.4430.212-Win64.zip into your project Plugins directory.
> Please update `immutable.uplugin->Plugins->WebBrowserWidget` to false and restart your UE4 editor.

### Setup

#### Blueprint

See the included sample widgets in `All`->`Plugins`->`Immutable Content` in the Unreal Editor content browser for examples of how to use the plugin in Blueprint. If you don't see a `Plugins` folder under `All` you may need to enable `Show Plugin Content` in the content browser's `Settings` menu.

#### C++

See `ImmutablePassport.h` for the C++ Passport API. Follow the same sequence of steps as the Blueprint widget example to initialise and connect Passport and retrieve account data.

### Quick Start

#### Passport Login Flow

See this Blueprint showing how to login to passport ![Passport Login Blueprint](PassportLoginFlow.jpg)

Here are the steps to login to passport:

1. `Initialise Passport` to initialise passport instance.
2. Check if there are stored credentials from previous login.
3. If stored credentials found, `ConnectSilent` uses the saved credentials to login to Passport.
4. When no stored credentials found or step 3 fails, attempt to make a new Connection to login to Passport using `Connect`. This will open the gamer's default browser and take them through the auth flow.

Once the gamer is connected to Passport, the SDK will store your credentials (access, ID, and refresh tokens).

> [!NOTE]
> We use the [Device Code Authorisation](https://auth0.com/docs/get-started/authentication-and-authorization-flow/device-authorization-flow#:~:text=Your%20Auth0%20Authorization%20Server%20redirects,authorized%20to%20access%20the%20API.) flow to authenticate and authorise gamers.

#### Log out of Passport

See this Blueprint showing how to logout from passport ![Passport Logout Blueprint](PassportLogoutFlow.jpg)

#### Imx Transfer

> Note: The transfers feature require pre-approval from Immutable. Please [contact us](https://docs.immutable.com/docs/x/contact/) before making use of it.

To transfer tokens of type ETH, ERC20 or ERC721 use `UImmutablePassport::ImxTransfer` method. See this Blueprint example showing how to use Imx Transfer

![Imx Transfer](ImxTransferFlow.png)

To transfer multiple NFTs in a single transaction use `UImmutablePassport::ImxBatchNftTransfer` method. See this Blueprint example showing how to use Imx Batch Nft Transfer

![Imx Batch Nft Transfer](ImxBatchNftTransfer.png)

#### zkEVM Send Transaction

To send a transaction on zkEVM use `UImmutablePassport::ZkEvmSendTransaction` method. See this Blueprint example showing how to use Zk Evm Send Transaction

![Zk Evm Send Transaction](ZkEvmSendTransaction.png)

### Android, iOS and macOS PKCE login (Unreal Engine 5.0+ only)

For Android, iOS and macOS, you can use the [Authorization Code Flow with Proof Key for Code Exchange (PKCE)](https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-proof-key-for-code-exchange-pkce) login flow instead of [Device Code Authorisation](https://auth0.com/docs/get-started/authentication-and-authorization-flow/device-authorization-flow#:~:text=Your%20Auth0%20Authorization%20Server%20redirects,authorized%20to%20access%20the%20API.). This means the gamer has one less step to complete and will be redirected back to the game after successfully authenticating.

To use this flow you will need to:

1. Define a deep link scheme for your game (e.g. `mygame://callback`)
2. Login to the [Immutable Developer Hub](https://hub.immutable.com/) and add the deeplink to your clients **Callback URLs** and **Logout URLs**
3. Set this deep link as your redirect URI in `Initialize Passport`

![Passport PKCE Login Blueprint](PassportPKCELoginFlow.png)

#### Unreal Editor Android setup

1. In Unreal Editor go to **Project Settings** -> **Android** -> **Advanced APK Packaging**
2. Add the following code inside the **Extra Settings for \<activity> section (\n to separate lines)** field:

```XML
<intent-filter>\n<action android:name="android.intent.action.VIEW" />\n<category android:name="android.intent.category.DEFAULT" />\n<category android:name="android.intent.category.BROWSABLE" />\n<data android:host="callback" android:scheme="mygame" />\n</intent-filter>
```

The application will now open when the device processes any link that starts with `mygame://callback`.

#### Unreal Editor iOS setup

1. In Unreal Editor go to **Project Settings** -> **iOS** -> **Extra PList Data**
2. Add the following code inside the **Additional Plist Data** field:

```
<key>CFBundleURLTypes</key><array><dict><key>CFBundleURLSchemes</key><array><string>mygame</string></array></dict></array>
```

After this set-up and the redirect URI you set in `Initialize Passport`, your game can log in using `mygame://callback`.

#### Unreal Editor macOS setup

Since there is no way to add extra plist data like iOS from the Unreal Editor Project Settings, you must edit the Engine's default `Info.plist`.

1. In your preferred IDE, open the Engine's `Info.plist` file (e.g. `Engine/Source/Runtime/Launch/Resources/Mac/Info.plist`)
2. Add the following code inside the root `<dict>...</dict>`:

```
<key>CFBundleURLTypes</key>
<array>
<dict>
<key>CFBundleURLSchemes</key>
<array>
<string>mygame</string>
</array>
</dict>
</array>
```

After setting up and specifying the redirect URI in `Initialize Passport`, the user will be automatically redirected back to the game through `mygame://callback` upon completing the login process.

See the [sample game](https://github.com/immutable/sample-unreal-game) for an example of how to set up PKCE for Android, iOS and macOS.

## Supported Functionality


| Method | Description |
|-----------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Connect | Log into Passport using [Device Code Authorisation](https://auth0.com/docs/get-started/authentication-and-authorization-flow/device-authorization-flow#:~:text=Your%20Auth0%20Authorization%20Server%20redirects,authorized%20to%20access%20the%20API.) |
| ConnectSilent | Attempts to login using stored credentials |
| ConnectPKCE | (Android, iOS and macOS on Unreal Engine 5.0+ only) Log into Passport using [Authorization Code Flow with Proof Key for Code Exchange (PKCE)](https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-proof-key-for-code-exchange-pkce) |
| CheckStoredCredentials | Checks if there are stored credits from previous login |
| GetAddress | Gets Wallet Address |
| GetEmail | Get Email Address associated with the Wallet Address |
| ImxTransfer | ImxTransfer used to send tokens of type ETH, ERC20, ERC721 to reciever's address |
| ImxBatchNftTransfer | ImxBatchNftTransfer used to send multiple Nft tokens in a single transaction to reciever's address |
| GetEmail | Get Email Address associated with the Wallet Address |
| zkEVM request accounts | This method attempts to authenticate the user and initialises their Passport wallet before returning an array of wallet addresses |
| zkEVM get balance | Returns the balance of the account of given address in wei |
| zkEVM send transaction | Creates new message call transaction or a contract creation, if the data field contains code |


See the [ImmutablePassport.h](https://github.com/immutable/unreal-immutable-sdk/blob/dc39324db204f2ba30e9c9f0ca25c070987785cb/Source/Immutable/Public/Immutable/ImmutablePassport.h#L115C8-L115C8) header for the full API.

## Examples

- **Sample Blueprints** - see the [sample blueprints](https://github.com/immutable/unreal-immutable-sdk/tree/main/Content/BlueprintSampleContent) for examples of how to use the Immutable Unreal SDK.

- **Sample Game** - see the [sample game](https://github.com/immutable/sample-unreal-game) for example of how to use the Immutable Unreal SDK.
* [Immutable X](https://docs.immutable.com/docs/x/sdks/unreal)
* [Immutable zkEVM](https://docs.immutable.com/docs/zkEVM/sdks/unreal)

## Plugin Maintainers' Guide

Expand All @@ -215,7 +29,7 @@ If not Rider, Visual Studio is fine and even better with the Resharper plugin.

### Getting Started

See [user guide](#user-guide) to install the plugin, with one caveat: If you want to open the project and plugin in an IDE you'll need to create your Unreal project as a C++ project. If you've already accidentally created your Unreal project as BluePrint-only you can convert it to a BluePrint-and-C++ project by adding any C++ class from the `Add New C++ Class` option in the Unreal Editor's `File` menu.
See [documentation](#documentation) on how to install the plugin, with one caveat: If you want to open the project and plugin in an IDE you'll need to create your Unreal project as a C++ project. If you've already accidentally created your Unreal project as BluePrint-only you can convert it to a BluePrint-and-C++ project by adding any C++ class from the `Add New C++ Class` option in the Unreal Editor's `File` menu.

### Debugging the Embedded Browser

Expand Down
Loading