Communicating with Embed Hub

There are several methods of sending data to Embed Hub to modify it on load or in real-time. This page explores controls that allow you to manipulate Embed Hub from your own site.

This guide covers:

• Query parameters
• Message events
• JavaScript API

User Delegated Token

A User Delegated Token (UDT) can be used to securely authenticate users in game via the Embed Hub or vice versa. If you are using the mod.io SDK and have authenticated the user, the UDT can be fetched by calling GetUserDelegationTokenAsync. Note: If your browser rejects the UDT because of its length, you can increase the buffer size of the browser, or contact us to discuss different ways to pass the UDT to Embed Hub.

Query parameters

The following table details the available query parameters available by modifying the URL passed into the src attribute of the <iframe>.

Parameter	Required?	Description
game_id	Yes	Your game's ID
version	Yes	An identifier for your Embed Hub
hash	If game is not live	A random string of characters required to view a hidden game's hub
tags		Default to filtering on a specfic tag (users will be unable to deselect this from the filters)
portal		Sets a portal header on every request. See Targeting a portal for more info
platform		Sets a platform header on every request. See Targeting a platform for more info
lang		Sets the language of Embed Hub. See Localization for available languages
featured		Shows a number of trending mods that have the specified tag in a carousel at the top of the mod browse page
featured_count		The number of featured mods to show if the 'featured' parameter is set (defaults to 5)
udt		Authenticate a user by passing in a User Delegated Token

Message events

A number of commands can be sent to and received from Embed Hub using the JavaScript message API. Each event should contain an object with one or more properties prefixed with modio and the corresponding data. These are listed below, the more complex data structures are described in detail as well.

To Embed Hub

Key	Data type	Description
modioAuth	IModioAuth	Authenticate a user by passing in either an ID token from your game's Open ID setup and optional email, or a UDT
modioCSS	string	Sets Custom CSS, as described on the Custom CSS page
modioFilter	IModioFilter	Sets a tag to force filtering on, or a featured tag
modioHome	true	Navigates Embed Hub back to the home page
modioLang	string	Sets the language of Embed Hub. See Localization for available languages
modioPlatform	string	Sets a platform header on every request. See Targeting a platform for more info
modioPortal	string	Sets a portal header on every request. See Targeting a portal for more info
modioQuery	IModioQuery	Search or filter mods by name or tags
modioScroll	IModioScroll	Sets the scroll position of the containing site
modioSettings	IModioSettings	Modify the settings of your Embed Hub, as described on the settings page
modioStyle	IModioStyle	Modify the style of your Embed Hub, as described on the theme page
modioUrl	string	Informs Embed Hub of the URL of the containing site
modioWindow	number	Informs Embed Hub of the height of the user's browser window

IModioAuth

{
  "id_token": string
  "access_token": string
  "email": string
}

IModioFilter

{
  "tags": string
  "featured": string
  "featuredCount": number
}

IModioQuery

{
  "_q": string
  "tags-in": string
}

IModioScroll

{
  "frameTop": string
  "scrollY": string
}

IModioSettings

{
  "agreementUrls": string[]
  "allowAddingMods": boolean
  "allowCommenting": boolean
  "allowDownloading": boolean
  "allowEditingMods": boolean
  "allowFiltering": boolean
  "allowInfiniteScroll": boolean
  "allowLinks": boolean
  "allowRating": boolean
  "allowSearching": boolean
  "allowSubscribing": boolean
  "companyName": string
  "filterRightSide": boolean
  "minAge": number
  "nameRightSide": boolean
  "showCollection": boolean
  "showComments": boolean
  "showGuides": boolean
  "showSortTabs": boolean
  "showUserAvatars": boolean
  "ugcPerPage": number
}

IModioStyle

{
  "activeButtonBorderColor": string
  "activeButtonBorderColorHover": string
  "activeButtonColor": string
  "activeButtonColorHover": string
  "buttonRadius": number
  "inputBackgroundColor": string
  "linkColor": string
  "modalBackground": string
  "pageBackground": string
  "primaryButtonBorderColor": string
  "primaryButtonBorderColorHover": string
  "primaryButtonColor": string
  "primaryButtonColorHover": string
  "secondaryButtonBorderColor": string
  "secondaryButtonBorderColorHover": string
  "secondaryButtonColor": string
  "secondaryButtonColorHover": string
  "tileBackgroundColor": string
  "tileBorderColor": string
  "tileBorderRadius": number
  "tileBorderWidth": number
}

From Embed Hub

Key	Data type	Description
modioAuth	'refresh'	Informs the containing site that the provided ID token has expired or is invalid and should be refreshed
modioHeight	number	Informs the containing site of Embed Hub's scroll height
modioInit	true	Informs the containing site that Embed Hub has loaded
modioPage	string	Informs the containing site of the current page Embed Hub is on
modioScroll	number	Used to control the vertical scroll position of the containing window

JavaScript API

The Embed Hub has a JavaScript API that is useful for calling functions directly when the Hub is embedded in-game. These are listed below, with their relevant details and required parameters.

From the Embed Hub

To receive data from the game, the Embed Hub expects a JavaScript object named modio on the global JS object which supports the following functions:

Function	Parameters	Description
getAuthToken		Used to get a UDT for the logged in user from the game
getActivatedIds		Used to get the list of activated mod IDs from the game
getLocalMods		Used to get the list of locally installed mods from the game
getLocalActivatedIds		Used to get the list of activated local mod IDs from the game
getLanguage		Used to get the language the game is using
getPlatform		Used to get the platform the game is running on
getPortal		Used to get the portal the game is authenticated with
setAuthToken	token: string	Used to provide a UDT of the logged in user to the game which can be exchanged for an access token
setUserId	userId: int	Used to set the logged in user's ID on the game
setActivatedIds	modIds: array<int>	Used to set the list of activated mod IDs on the game
setLocalActivatedIds	modIds: array<string>	Used to set the list of activated local mod IDs on the game
notifySubscriptionChange	modId: int, isSubscribed: boolean	Used to notify the game that a mod has been subscribed to or unsubscribed from
notifyActivationChange	modId: int, isActivated: boolean	Used to notify the game that a mod has been activated or deactivated
notifyLocalActivationChange	modId: int, isActivated: boolean	Used to notify the game that a local mod has been activated or deactivated

To the Embed Hub

To call functions on the Embed Hub from in-game, The Hub exposes a JavaScript object named modioEmbedHub on the global JS object which supports the following functions.

Function	Parameters	Description
echo	...args: any	Returns an array of the parameters supplied to the function
getAuthToken		Used to get a UDT of the currently authenticated user from the Embed Hub. Note: as this operation is asynchronous, it will call setAuthToken with the UDT on the modio JS object above
setAuthToken	token: string	Used to provide a UDT to the Embed Hub which will authenticate the user
isUserAuthenticated		Returns true if the current user is authenticated within the Embed Hub
logout		Used to log the current user out of the Embed Hub

Authentication

There are 3 ways to automatically authenticate users when opening the Embed Hub in-game or in your web browser as explained above. We recommend using one of these approaches when the user is already authenticated (i.e. by the game client), to ensure a seamless experience.

1. Passing in a UDT as a URL query parameter when loading the Embed Hub.
2. Using the JavaScript message event modioAuth key, to pass in a user's ID token or UDT.
3. Using the JavaScript API setAuthToken function, to pass a UDT for the current user.