Skip to content

Deprecate prefab Admin Console; migrate command reference to built-in console page #113

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

Open
allister-beamable wants to merge 1 commit into
base: unity/v5.1
Choose a base branch
from
Open

Deprecate prefab Admin Console; migrate command reference to built-in console page #113

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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 added docs/media/imgs/default-gem-icon.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 1 addition & 1 deletion docs/unity/getting-started/installing-beamable.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ Open the Beamable Login Window by clicking the Beamable button in the Unity tool
Now you are ready to start your first Beamable project!

## Say _hello_ to Beamable!
To confirm that you have a working Beamable setup, we will pull in the `BeamableBehavior` component and make sure we can access a player account using the [Admin Console](../user-reference/runtime-systems/admin-console.md).
To confirm that you have a working Beamable setup, we will pull in the `BeamableBehaviour` component and make sure we can access a player account using the [Admin Console](../user-reference/runtime-systems/admin-console.md).

![Animated walkthrough of the Unity Editor in play mode: the Beamable runtime initializes in the Console, then the Admin Console opens to confirm access to a player account.](../../media/imgs/getting-started.gif)

Expand Down
2 changes: 1 addition & 1 deletion docs/unity/user-reference/SUMMARY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
- [Admin Console](runtime-systems/admin-console.md)
- Editor Systems
- [Editor Login](editor-systems/unity-editor-login.md)
- [Beam Library](editor-systems/beam-library.md)
- [Beam Samples](editor-systems/beam-library.md)
- [Offline Mode](editor-systems/offline-mode.md)
- [Autogenerated SDK](editor-systems/autogenerated-sdk.md)
- [Builds & Environments](editor-systems/builds-environments.md)
Expand Down
2 changes: 1 addition & 1 deletion docs/unity/user-reference/beamable-services/bi/ab-testing-overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -117,7 +117,7 @@ Access these values programmatically via **get** as `game.private.player`.

### Debugging manifests

For debugging the manifests, game players can use the Admin Flow to enter commands.
For debugging the manifests, game players can use the Admin Console to enter commands.

**Commands**

Expand Down
3 changes: 3 additions & 0 deletions ...unity/user-reference/beamable-services/profile-storage/content/content-unity.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -196,6 +196,9 @@ Content filter strings can be entered into the Content Manager's search box, or
| `tag:a` | returns all content elements that have the `"a"` tag |
| `tag:a b` | returns all content elements that have the `"a"` tag and the `"b"` tag |

!!! info "Good to know: tag filtering and `OmitContentManifestTags`"
If you enable `OmitContentManifestTags` on `ContentConfiguration`, the manifest your game fetches at runtime is downloaded without tags. Tag-based `GetManifest` and `ContentQuery` filters (for example, `tag:weapon`) then return no results in builds. The in-Editor Content Manager search box is unaffected, since it filters local content.

**Id Filtering:** To filter by content id, use the `id` filter constraint, or use no constraint at all. The `id` filter constraint is the default constraint. The following table shows examples of id constraints.

| Filter String | Description |
Expand Down
130 changes: 8 additions & 122 deletions docs/unity/user-reference/editor-systems/beam-library.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,131 +1,17 @@
# Beam Library overview
# Beam Samples overview

The Beam Library is a collection of package samples and prefabs to help get you started learning the Unity SDK. To open the Beam Library, click on the Beamable Button (at the top-right of the Unity window), and select _Beam Library_.
The **Beam Samples** window is a collection of Lightbeam samples that help you get started learning the Unity SDK. To open it, click the Beamable button (at the top-right of the Unity window) and select _Beam Samples_.

![Select "Open Beam Library" from the Beamable Button](../../../media/imgs/533076e9cddc444ecdf9be5f5e2310b7d293fbc95b5792a9959a803433fd7955-image.png){width="400px"}
![Select "Open Beam Samples" from the Beamable button](../../../media/imgs/533076e9cddc444ecdf9be5f5e2310b7d293fbc95b5792a9959a803433fd7955-image.png){width="400px"}

Now the _Beam Library_ should be open.
Now the _Beam Samples_ window should be open.

![Beam Library Window](../../../media/imgs/7b0d4957423d75029795d0d58132b6e7ca953f448a97b7057065519465467364-image.png){width="400px"}
![The Beam Samples window](../../../media/imgs/7b0d4957423d75029795d0d58132b6e7ca953f448a97b7057065519465467364-image.png){width="400px"}

Each card represents a Package Sample. When you click the "Open Scene" button, a Beamable sample will be added to your assets folder under `Assets/Samples/Beamable`.
Each card represents a Lightbeam sample. Selecting a sample copies it into your project under `Assets/Samples/Beamable`.

## Admin Console

Most of the package samples are entire Scenes that help you get started understanding a topic. However, the _Admin Console_ is unique, because it is a prefab that gets added to your project.The prefab is helpful to dropping into your project, because you can use it to interact with Beamable at runtime.
!!! warning "Deprecated: prefab-based Admin Console"
Earlier SDK versions shipped the Admin Console as a prefab (the "Admin Flow" feature) that you added to your scene from this window. That prefab is deprecated and scheduled for removal in a future release. The Admin Console is now a built-in runtime integration that requires no prefab — see [Admin console](../runtime-systems/admin-console.md) for setup, the built-in command reference, and the custom-command API.


### Admin Console prefab

#### Overview

The **Admin Flow** Feature Prefab provides developers with debugging capabilities.

The purpose of this feature is to offer the game maker an in-game UI for executing game commands and cheats.

#### Usage

The Admin Flow can be opened at runtime in multiple ways:

- Within the Unity Editor, press the "~" key
- Within a Mobile Build, use a "three-finger swipe-up gesture"

#### The user interface

![The Beamable "Admin Flow" UI in the Unity Game Window](../../../media/imgs/admin-flow-ui-game-window.png){width="200px"}

#### Adding to your project

The Admin Prefab is accessible via the _Beam Library_ window. You can open the _Beam Library_ and add the admin prefab to your scene.

#### Admin commands

Once the Admin Flow is open, type an admin command into the input field and press return.

There are built-in Beamable admin commands and game makers can create custom admin commands for additional functionality.

##### Using Beamable admin commands

| Command | Detail |
| :---------------------------------------------- | :------------------------------------------------------------------------------------------------------------------- |
| `help` | Shows the list of all admin commands |
| `TRACK_PAYMENT` | Track a test payment audit |
| `ECHO <message>` | Repeat message to console. |
| `WHERE <command>` | Find where a specific console command was registered from, if it was registered with a DBeamConsoleCommand attribute |
| `account_toggle` | emit an account management toggle event |
| `account_list` | list user data |
| `IDFA` | print advertising identifier |
| `RESET` | Clear the access token and start with a fresh account |
| `LOCALNOTE [<delay> [<title> [<body>]]]` | Send a local notification. Default delay is 10 seconds. |
| `TIMESCALE <value> \| variable` | Sets the current timescale |
| `SUBSCRIBER_DETAILS` | Query subscriber details |
| `DBID` | Show current player PlayerId |
| `ENTITLEMENTS <symbol> <state>` | Show current player entitlements |
| `HEARTBEAT <dbid>` | Get heartbeat of a user |
| `LOGIN_ACCOUNT <email> <password> ` | Log in to the PlayerId designated by the given username and password |
| `MAIL_GET <category>` | Get mailbox messages |
| `MAIL_UODATE <id> <state> <acceptAttachments> ` | Update a mail |
| `REGISTER_ACCOUNT <email> <password>` | Registers this PlayerId with the given username and password |
| `EXPIRE_TOKEN` | Expires the current access token to trigger the refresh flow |
| `CORRUPT_TOKEN` | Corrupts the current access token to trigger the refresh flow |
| `TEST-ANALYTICS` | Run 1000 events to test batching/load |
| `IAP_BUY <listing> <sku>` | Invokes the real money transaction flow to purchase the given item_symbol. |
| `IAP_PENDING` | Displays pending transactions |

#### Force-enabled

Within the Unity Editor, press the "~" key to open the in-game console. This always works, regardless of player privileges or "Admin Flow" settings.

On device, use a three-finger swipe gesture to open the in-game console. This only works if the player has sufficient privileges, or if the "Admin Flow" settings specify the console should always be available.

!!! info "Best Practice"

- For security reasons, it is not recommended to allow a players to access the in-game console. Beamable has precautions in place to prevent this

The in-game console, on-device, will **only** appear if the force-enabled checkbox is true, or if the current player's account has tester, developer, or admin privileges.

The Beamable Portal allows game makers to grant player privileges. This privilege-requirement only applies to device, not the Unity Editor.


### AdminFlow API

#### Creating custom admin commands

Game makers can create custom admin commands for additional functionality.

AdminFlowCustomCommandExample.cs
```csharp
using Beamable.ConsoleCommands;
using UnityEngine;

namespace Beamable.Examples.Features.AdminFlow
{
[BeamableConsoleCommandProvider]
public class CustomConsoleCommandProvider
{
[BeamableConsoleCommand ("Add", "A sample addition command", "Add <int> <int>")]
public string Add(string[] args)
{
var a = int.Parse(args[0]);
var b = int.Parse(args[1]);
return "Result: " + (a + b);
}
}

/// <summary>
/// Demonstrates <see cref="AdminFlow"/>.
/// </summary>
public class AdminFlowCustomCommandExample : MonoBehaviour
{
// Unity Methods --------------------------------
protected void Start()
{
Debug.Log($"Start() Instructions...\n" +
" * Run The Scene\n" +
" * Type '~' in Unity Game Window to open Admin Console\n" +
" * Type 'Add 5 10'\n" +
" * See 'Result: 15' in Unity Console Window\n");
}
}
}
```
70 changes: 70 additions & 0 deletions docs/unity/user-reference/runtime-systems/admin-console.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,76 @@ Use the `help` command to list every registered command and its usage:
> help
```

## Built-in commands

Beamable registers these commands by default:

| Command | Detail |
| :---------------------------------------------- | :------------------------------------------------------------------------------------------------------------------ |
| `help` | Show the list of all admin commands |
| `TRACK_PAYMENT` | Track a test payment audit |
| `ECHO <message>` | Repeat a message to the console |
| `WHERE <command>` | Find where a console command was registered from, if it was registered with a `BeamableConsoleCommand` attribute |
| `account_toggle` | Emit an account management toggle event |
| `account_list` | List user data |
| `IDFA` | Print the advertising identifier |
| `RESET` | Clear the access token and start with a fresh account |
| `LOCALNOTE [<delay> [<title> [<body>]]]` | Send a local notification (default delay is 10 seconds) |
| `TIMESCALE <value> \| variable` | Set the current timescale |
| `SUBSCRIBER_DETAILS` | Query subscriber details |
| `DBID` | Show the current player's PlayerId |
| `ENTITLEMENTS <symbol> <state>` | Show the current player's entitlements |
| `HEARTBEAT <dbid>` | Get the heartbeat of a user |
| `LOGIN_ACCOUNT <email> <password>` | Log in to the PlayerId designated by the given username and password |
| `MAIL_GET <category>` | Get mailbox messages |
| `MAIL_UPDATE <id> <state> <acceptAttachments>` | Update a mail |
| `REGISTER_ACCOUNT <email> <password>` | Register this PlayerId with the given username and password |
| `EXPIRE_TOKEN` | Expire the current access token to trigger the refresh flow |
| `CORRUPT_TOKEN` | Corrupt the current access token to trigger the refresh flow |
| `TEST-ANALYTICS` | Run 1000 events to test batching and load |
| `IAP_BUY <listing> <sku>` | Invoke the real-money transaction flow to purchase the given item |
| `IAP_PENDING` | Display pending transactions |

## Custom commands

You can register your own commands to extend the console. Annotate a class with `[BeamableConsoleCommandProvider]` and each command method with `[BeamableConsoleCommand]`:

CustomConsoleCommandExample.cs
```csharp
using Beamable.ConsoleCommands;
using UnityEngine;

namespace Beamable.Examples.AdminConsole
{
[BeamableConsoleCommandProvider]
public class CustomConsoleCommandProvider
{
[BeamableConsoleCommand("Add", "A sample addition command", "Add <int> <int>")]
public string Add(string[] args)
{
var a = int.Parse(args[0]);
var b = int.Parse(args[1]);
return "Result: " + (a + b);
}
}

/// <summary>
/// Demonstrates a custom <see cref="BeamableAdminConsole"/> command.
/// </summary>
public class CustomConsoleCommandExample : MonoBehaviour
{
// Unity Methods --------------------------------
protected void Start()
{
Debug.Log($"Start() Instructions...\n" +
" * Run the scene\n" +
" * Type '~' in the Unity Game window to open the Admin Console\n" +
" * Type 'Add 5 10'\n" +
" * See 'Result: 15' in the Unity Console window\n");
}
}
}
```

## Logging to the console

Expand Down
Loading