Skip to content

Reference UI Kit

The Reference UI Kit is a set of screen examples to refer to when you implement Hive Axyl SDK features in your app. It provides screens that you must show directly to users, such as the login screen and the account management screen, prebuilt as resources and code.

A recipe is source code that groups Hive Axyl SDK calls by purpose, and the Reference UI Kit is a set of prebuilt resources for the screens that present those features to users. By using them together, you can implement account and authentication features in your app without designing screens from scratch. To learn what a recipe is, see the Username login practical guide.

Provided screens

The Reference UI Kit provides four screens needed for accounts and authentication. In each screen guide, review the screen example, the recipes to connect, and what to check when you apply the screen.

  • Login screen: The screen you open when the user chooses the login method to use
  • Username login screen: The screen you open when the user logs in or creates an account with a username and password
  • Password change screen: The screen you open when the user changes the password of a username account
  • Account management screen: The screen you open when the user manages linked login methods or logs out

Scope of the Reference UI Kit

Because the Reference UI Kit handles only the screens, login does not work just by importing the screen resources and opening a screen. The screens work only after the app connects the screen resources to recipes or Hive Axyl SDK methods. The responsibilities of the screen resources, the recipes, and the app are as follows.

  • Screen resources: Displaying the screen, receiving user input, forwarding user input events, and changing the screen display based on the data and state they receive
  • Recipes: Calling the Hive Axyl SDK in a set order with the input values the app passes, returning the processing results, and deciding when to move to the authentication screen of an external authentication provider that authenticates the user on the app's behalf, such as Google or Apple
  • App: Passing the values to display on the screen, such as the login method list, login method icons, and failure messages; calling recipes or Hive Axyl SDK methods in response to user input events; and displaying messages and moving between screens based on the processing results

Because the screen resources do not reference the Hive Axyl SDK directly, you can import and use just the screens without changing your app's authentication structure. The recipes and Hive Axyl SDK methods to connect differ for each screen. Before you apply a screen, first check the related recipes in each screen guide. For the recipe call order and what the app handles for each result, see the recipe usage examples.

Login method icons

Because of copyright issues, the screen resources do not include the brand icons of external authentication providers, so the app must prepare the icons and pass them to the screen. Where to get the icons for each login method is as follows.

Use downloaded icons as they are, without changing their shape, proportions, or colors. Adjust only the padding so that the overall size is 24×24, and then pass them. The screen displays these icons at 20×20. If you use lookalike icons instead of the official ones, you may violate each provider's brand guidelines. A login method whose icon you do not pass is displayed as a chip with text instead of an image in the icon position, so leave it that way until you get the official icon.

Supported environments

The environments that the screen resources support are as follows. First check that your project's Unity version matches the verified version stated in the repository.

  • Development environment: Unity
  • Unity version: The verified version stated in the repository
  • Devices: PC, mobile
  • Screen orientation: Portrait, landscape

Because a single screen resource handles all of the devices and screen orientations above, you do not need to import separate resources for different aspect ratios or resolutions. Check the resources to import in the Applying to Unity section of each screen guide.

Import screen resources

Import the screen resources from the hive-axyl-reference-ui repository. Unlike the Hive Axyl SDK, which you install as a package, you copy the folders into your project, so after importing them you can freely modify them to fit your app's design.

The Reference UI Kit uses a different versioning scheme from the Hive Axyl SDK. Updating the Hive Axyl SDK does not mean that you also need to update the screen resources.

TextMesh Pro essential resources

The screen resources use TextMesh Pro (TMP), Unity's text display feature, so your project must have the TMP essential resources. Without the essential resources, errors occur in the text of the screen resources. If you have not imported the essential resources yet, as in a newly created project, first import them by selecting Window > TextMeshPro > Import TMP Essential Resources in the Unity Editor.

Folders to copy

All screen resources in the repository are under unity/UI-Kit/. If you copy only the screen folders, the shared widgets, fonts, and assembly definition file are left out, and the screens do not display or work correctly. Along with the folders of the screens to import, you must also copy the common folder, the fonts folder, and the assembly definition file. The repository path of each folder and file is as follows.

Target Repository path Contents
Login screen folder unity/UI-Kit/Login Screen resources and the list of shared widgets the screen uses
Username login screen folder unity/UI-Kit/UsernameLogin Screen resources and the list of shared widgets the screen uses
Password change screen folder unity/UI-Kit/PasswordChange Screen resources and the list of shared widgets the screen uses
Account management screen folder unity/UI-Kit/Account Screen resources and the list of shared widgets the screen uses
Common folder unity/UI-Kit/Common Widgets that multiple screens share, such as the close button, the failure toast (a short message that notifies the user of a failure), action buttons, and input fields
Fonts folder unity/UI-Kit/Fonts Fonts used to display text on the screens
Assembly definition file unity/UI-Kit/UIKit.asmdef Setting that groups the scripts of the screen resources into a single assembly. An assembly is the unit in which Unity groups and compiles scripts

The unity/UI-Kit/Editor folder contains development tools that regenerate widgets and fonts, so you do not need to copy it into your app project.

.meta files

A .meta file is a file that Unity creates for each file in a project to record that file's identifier. The screen resources reference scripts, images, and fonts by these identifiers. If a .meta file is missing or a new identifier is issued, the references break and the screens do not display correctly.

If you copy whole folders in Finder or File Explorer, the .meta files move along with them. On the other hand, if you drag and drop the folders into the Project window of the Unity Editor, the .meta files may not be kept. When you first open a copied screen, if the Console window shows no Missing script warning (the warning that a script could not be found) and the screen displays normally, the references have been kept.

How to copy

The safest method is to copy the entire unity/UI-Kit folder to Assets/UI-Kit in your app project in Finder or File Explorer, and then delete the screen folders you do not use. You can also delete the Editor folder, which your app does not need. When you do this, do not delete the Common folder, the Fonts folder, or the UIKit.asmdef file; keep them.

You can copy them to a different location as long as it is inside the Assets/ folder, but you must meet the following conditions.

  • Keep the Resources/UIKit/ folder in each folder and the structure under it as is: The screen resources load widgets and images with UIKit/... paths relative to the Resources folder, so if you rename the folder or move subfolders, the resources may not be found when a screen opens
  • Place the screen folders, the common folder, the fonts folder, and the UIKit.asmdef file under the same parent folder: UIKit.asmdef groups the scripts under the same folder into a single assembly, so if you move only a screen folder elsewhere, its scripts are left out of the assembly and compile errors may occur

Assembly references

If your app has no assembly definition file, app scripts go into Assembly-CSharp, Unity's default assembly. Because autoReferenced in UIKit.asmdef is false, the default assembly does not reference it automatically. Therefore, app scripts in Assembly-CSharp cannot use screen resource types such as LoginScreen.

To open screens from app scripts, add Hive.Axyl.UIKit to references in your app's assembly definition file. If you already have an assembly definition file that you created to use recipes, add it to that file; otherwise, create a new one. Replace MyApp in the following example with the assembly name your app uses. Keep your existing settings and references as they are.

{
  "name": "MyApp",
  "references": [
    "Hive.Axyl.UIKit",
    "UnityEngine.UI"
  ]
}

Open and close screens

You open screens from app code instead of placing them in a Unity scene in advance. The repository does not include any scenes either. The app itself closes the screens it opens.

Open a screen

To open a screen, call that screen's Show() method, such as LoginScreen.Show() for the login screen. Show() creates its own canvas to display the UI and then opens the screen. You can call Show() from any scene in your app.

Pass Show() options that contain the values to display on the screen and the callbacks. A callback is app code that the screen calls when the user interacts with it. The following example opens the login screen and closes it when it receives a close request. Put the list of login methods to display in Providers, and put callbacks in OnProviderSelected and OnClose.

LoginScreen screen = null;
screen = LoginScreen.Show(new LoginScreenOptions
{
    Providers = LoginScreenOptions.DefaultProviders(),
    OnProviderSelected = id => { /* Call the recipe */ },
    OnClose = () => screen.Dismiss(),
});

Close a screen

Screens do not close by themselves. When you need to close a screen, such as when login succeeds, call Dismiss(). Even when the user selects the close button or presses Esc, the screen only calls OnClose, so call Dismiss() in OnClose to close it. The actions that call OnClose on each screen are as follows.

  • Login: Close button, Esc, or selecting the dark background behind the screen
  • Account management: Close button, Esc
  • Username login: Close button, Esc. Applies only when opened as a pop-up
  • Password change: Close button, Esc. Applies only when opened as a pop-up

The username login screen and the password change screen open as a pop-up if the Popup option is true, and as a full screen if it is false. When opened as a full screen, there is no close button, so call Dismiss() to close the screen when the app moves to another screen. If the user presses Esc while the confirmation pop-up is open on the account management screen, only the pop-up closes and the account management screen remains.

Input locking during request processing

How input is locked while the app processes a request, such as login or a password change, with the values received from a screen differs for each screen. What the app does for each screen is as follows.

Screen Input lock What the app does
Username login, password change The moment the user selects the login button or the confirm button, the screen locks the input fields and that button by itself When you keep showing the screen after processing ends, call SetBusy(false) to release the lock. If you do not call it, the user cannot enter input again. You do not need to call it when processing succeeds and you close the screen
Login, account management No lock. OnProviderSelected is called each time the user selects a login method button or a linking list item If you need to prevent buttons or items from being selected again while the request is being processed, handle it in the app

The username login screen and the password change screen also have SetSubmitEnabled(), which prevents input from being submitted with the login button or the confirm button. Use it when you must block submission for app-specific reasons that the screen cannot know by itself, such as server maintenance or terms not being accepted.

Next steps

Once you have decided which screens to import, start with the guides for those screens.