How Do I Show the Profile Widget in the Android SDK (v3)?

Use the Gameball profile widget to show customers their points, rewards, tiers, leaderboards, and history inside your Android app.

Before showing the profile widget, make sure the SDK is initialized and the customer has been registered using Initialize SDK and Initialize Customer Profile.

Basic Usage

Create a ShowProfileRequest and call showProfile from GameballApp.

val profileRequest = ShowProfileRequest.builder()
    .customerId("customer-123")
    .build()

GameballApp.getInstance(this).showProfile(
    this,
    profileRequest
)

// With session token override
GameballApp.getInstance(this).showProfile(
    this,
    profileRequest,
    sessionToken = "customer-token"
)

ShowProfileRequest profileRequest = ShowProfileRequest.builder()
    .customerId("customer-123")
    .build();

GameballApp.getInstance(this).showProfile(
    this,
    profileRequest
);

Request Parameters

string

Unique identifier for the customer whose profile will be displayed. Optional (omit for guest mode).

string

Specific section to open inside the widget (for example, "details_earn", "details_redeem"). If not set, the main profile view opens by default.

Hides the widget navigation bar when set to true. Defaults to false.

boolean

Shows a close button within the widget when set to true. Defaults to false.

string

Hex color string for the close button (for example, "#FF5733").
Only applies when showCloseButton is true.

string

Optional session token to override the global token for this specific request. Required in upcoming SDK v4.

string

Customer mobile number, used for channel merging. Available from v3.2.0.

string

Customer email address, used for channel merging. Available from v3.2.0.

Callback<String>

Handler for links the widget tags with gbExternalBrowser=true. When provided, the link is delegated to your app; otherwise the SDK opens it in the system browser. Available from v3.2.0.

Receives events the widget posts, such as game completion. Available from v3.2.0.

Validation Rules

No required fields (guest mode supported). Provide customerId for authenticated profiles.

Advanced Configuration

Open a Specific Section

Use openDetail to deep link into a specific section (for example, “earn” details):

val profileRequest = ShowProfileRequest.builder()
    .customerId("customer-123")
    .openDetail("details_earn")  // Open the earn points section
    .build()

Guest Mode (v3.1.1+)

// No customerId required
val guestRequest = ShowProfileRequest.builder()
    .showCloseButton(true)
    .build()

GameballApp.getInstance(this).showProfile(
    this,
    guestRequest
)

Custom Close Button

Show a custom-colored close button on the widget:

val profileRequest = ShowProfileRequest.builder()
    .customerId("customer-123")
    .showCloseButton(true)
    .closeButtonColor("#FF5733")
    .build()

Often paired with openDetail to guide users to a specific section when navigation is hidden.

Hide the widget’s internal navigation controls:

val profileRequest = ShowProfileRequest.builder()
    .customerId("customer-123")
    .openDetail("details_earn")
    .hideNavigation(true)
    .build()

Handle External Links (v3.2.0+)

Links the widget tags with gbExternalBrowser=true open in the system browser by default. Provide an externalLinkCallback to handle them yourself instead (for example, to open an in-app browser or route to a custom screen):

val profileRequest = ShowProfileRequest.builder()
    .customerId("customer-123")
    .externalLinkCallback(object : Callback<String> {
        override fun onSuccess(url: String) {
            // Open the link your own way, e.g. an in-app browser or a custom screen
            Log.d("GameballWidget", "External link: $url")
        }

        override fun onError(error: Throwable) {
            // Handle error
        }
    })
    .build()

When externalLinkCallback is set, the SDK delegates the link to your app and does not open the system browser.

Channel Merging (v3.2.0+)

Pass the customer’s mobile and email so Gameball can merge the customer’s channels:

val profileRequest = ShowProfileRequest.builder()
    .customerId("customer-123")
    .mobile("+201234567890")
    .email("customer@example.com")
    .build()

GameballApp.getInstance(this).showProfile(this, profileRequest)

Pass a widgetEventCallback to react to events the widget posts, such as a customer finishing a game. Each event arrives as a Map<String, Object> with a top-level type and a nested metadata map:

val profileRequest = ShowProfileRequest.builder()
    .customerId("customer-123")
    .widgetEventCallback(object : Callback<Map<String, Any?>> {
        override fun onSuccess(event: Map<String, Any?>) {
            val type = event["type"] as? String                        // e.g. "gameCompleted"
            val metadata = event["metadata"] as? Map<*, *>

            if (type == "gameCompleted") {
                val hasWon = metadata?.get("hasWon") as? Boolean ?: false
                val rewardName = metadata?.get("rewardName") as? String
                if (hasWon) {
                    // Refresh the customer's balance, show a win animation, etc.
                }
            }
        }

        override fun onError(error: Throwable) {
            // Handle malformed event payloads
        }
    })
    .build()

GameballApp.getInstance(this).showProfile(this, profileRequest)

`gameCompleted` Metadata

Field	Type	Description
`hasWon`	`Boolean`	Whether the customer won a reward this round
`rewardType`	`String?`	Reward category: `Default`, `Friend`, `Bonus`, `CustomText`, `Streak`, `NoReward`
`discountType`	`String?`	Coupon kind when the win is a coupon: `Fixed`, `Percentage`, `FreeShipping`, `FreeProduct`, `Custom`, `RechargeFixed`, `RechargePercentage`, `ExternalReward`. `null` for non-coupon wins
`rewardName`	`String?`	Localized, human-readable reward name
`campaignId`	`String`	Challenge or campaign identifier
`campaignType`	`String?`	Game type: `spinTheWheel`, `slotMachine`, `quiz`, `scratchCard`, `matchCards`, `catcher`, `ticTacToe`, `shooter`, `puzzle`, `tapTarget`, `highwayDrive`

All gameCompleted values arrive as String or Boolean. There are no numeric fields.

Dismiss the widget programmatically from your app. The call is a no-op when no widget is showing:

GameballApp.getInstance(this).hideProfile()

The widget can also dismiss itself from the web side by calling window.GameballWidget.closeWidget().

Implementation Examples

Show Profile from a Button

Display the profile widget when the user taps a button.

class MainActivity : AppCompatActivity() {

  override fun onCreate(savedInstanceState: Bundle?) {
      super.onCreate(savedInstanceState)
      setContentView(R.layout.activity_main)

      findViewById<Button>(R.id.btnShowProfile).setOnClickListener {
          showCustomerProfile()
      }
  }

  private fun showCustomerProfile() {
      val profileRequest = ShowProfileRequest.builder()
          .customerId("customer-123")
          .build()

      GameballApp.getInstance(this).showProfile(
          profileRequest,
          object : Callback<Boolean> {
              override fun onSuccess(success: Boolean) {
                  // Profile displayed
              }

              override fun onError(error: Throwable) {
                  Toast.makeText(
                      this@MainActivity,
                      "Error: ${error.message}",
                      Toast.LENGTH_SHORT
                  ).show()
              }
          }
      )
  }
}

public class MainActivity extends AppCompatActivity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        findViewById(R.id.btnShowProfile).setOnClickListener(v -> {
            showCustomerProfile();
        });
    }

    private void showCustomerProfile() {
        ShowProfileRequest profileRequest = ShowProfileRequest.builder()
            .customerId("customer-123")
            .build();

        GameballApp.getInstance(this).showProfile(
            profileRequest,
            new Callback<Boolean>() {
                @Override
                public void onSuccess(Boolean success) {
                    // Profile displayed
                }

                @Override
                public void onError(Throwable error) {
                    Toast.makeText(
                        MainActivity.this,
                        "Error: " + error.getMessage(),
                        Toast.LENGTH_SHORT
                    ).show();
                }
            }
        );
    }
}

Open the profile widget when the user taps a “Rewards” tab:

bottomNavigationView.setOnItemSelectedListener { item ->
    when (item.itemId) {
        R.id.nav_rewards -> {
            val profileRequest = ShowProfileRequest.builder()
                .customerId(getCurrentCustomerId())
                .build()

            GameballApp.getInstance(this).showProfile(profileRequest, callback)
            true
        }
        else -> false
    }
}

The profile widget typically includes:

Customer Info

Display name, points balance, and tier level.

Reward Campaigns

Available rewards, missions, and how to earn them.

Leaderboard

Customer ranking and top performers.

Transaction History

History of points earned and redeemed.

The content, layout, and branding of the profile widget can be configured from your Gameball dashboard.

Best Practices

Make Access Easy

Place entry points to the profile widget in prominent locations (for example, main navigation, profile screen, or a dedicated Rewards tab).

Use Badges

Show badges or indicators when a customer has new rewards or achievements to view.

Use Deep Linking

Use the openDetail parameter to open specific sections based on context (for example, after checkout, open the rewards section).

Handle Errors Gracefully

Always implement the error callback to show friendly messages if the widget fails to load (for example, due to network issues).

Consider showing the profile widget immediately after a customer earns points or unlocks a reward to reinforce engagement.

Overview

Web & POS Integration

Mobile Integration

How Do I Show the Profile Widget in the Android SDK (v3)?

Open the Gameball Profile Widget

Basic Usage

Request Parameters

Validation Rules

Advanced Configuration

Open a Specific Section

Guest Mode (v3.1.1+)

Custom Close Button

Hide Navigation

Handle External Links (v3.2.0+)

Channel Merging (v3.2.0+)

Widget Events (v3.2.0+)

`gameCompleted` Metadata

Dismiss the Widget (v3.2.0+)

Implementation Examples

Show Profile from a Button

Bottom Navigation Integration

What the Widget Shows

Customer Info

Reward Campaigns

Leaderboard

Transaction History

Best Practices

​Open the Gameball Profile Widget

​Basic Usage

​Request Parameters

​Validation Rules

​Advanced Configuration

​Open a Specific Section

​Guest Mode (v3.1.1+)

​Custom Close Button

​Hide Navigation

​Handle External Links (v3.2.0+)

​Channel Merging (v3.2.0+)

​Widget Events (v3.2.0+)

​gameCompleted Metadata

​Dismiss the Widget (v3.2.0+)

​Implementation Examples

​Show Profile from a Button

​Bottom Navigation Integration

​What the Widget Shows

Customer Info

Reward Campaigns

Leaderboard

Transaction History

​Best Practices

Open the Gameball Profile Widget

Basic Usage

Request Parameters

Validation Rules

Advanced Configuration

Open a Specific Section

Guest Mode (v3.1.1+)

Custom Close Button

Hide Navigation

Handle External Links (v3.2.0+)

Channel Merging (v3.2.0+)

Widget Events (v3.2.0+)

`gameCompleted` Metadata

Dismiss the Widget (v3.2.0+)

Implementation Examples

Show Profile from a Button

Bottom Navigation Integration

What the Widget Shows

Best Practices