JSON Configuration Reference¶

To customize GetSocial UI you have to provide custom assets (drawables, fonts) and json configuration file.

Default JSON¶

default.json is a UI configuration file that we use for the default theme of the GetSocial UI. We recommend to use it as a starting point in building your json UI configuration.

In the following sections, json configuration file structure will be described.

Base Design¶

Base design object has a set of properties that describe base design mockup settings and UI behavior on different screen sizes. GetSocial SDK needs to know base design width, height, ppi and scale-mode to calculate UI element sizes on screens with various resolutions and pixel densities.

Width and height is a pixel resolution of base design mockup PSD, ppi is a density resolution measured in pixels/inch.

Base design section is mandatory in json configuration. Here is example is taken from default.json:

"base-design": {
    "scale-mode": "scale-with-screen-size",
    "width": 320,
    "height": 640,
    "ppi": 72
}

Scaling Modes¶

For now, SDK support only scale-with-screen-size scaling mode.

Scale with screen size mode

Using the scale-with-screen-size mode, positions and sizes can be specified according to the pixels of a specified base design resolution. If the current screen resolution is larger than the base design resolution, the canvas will keep the aspect ratio of the base design but will scale up to fit the screen. If the current screen resolution is smaller than the base design resolution, the canvas will similarly be scaled down to fit. In any case SDK will keep the aspect ratio of the base design.

If the current screen resolution has a different aspect ratio than the base design resolution, the SDK will make the canvas resolution deviate from the base design resolution to respect the aspect ratio of the screen. SDK will make sure that canvas will always be fully visible (not cropped) a fit the same amount of content on any screen size and density, see illustration below.

Assets Base Path¶

Property assets-base-path specifies common part of the path for the resources, e.g. if assets are located in Resources/getsocial/assets/getsocial/Assets/StreamingAssets/getsocial/ folder, configuration should be following:

"assets-base-path": "getsocial"

Text Styles Definition¶

text-styles object contains all the text style definitions that can be used to configure elements under elements object.

Each text style has the following properties:

font - mandatory parameter, can be one of two:
- font name registered in the system, e.g. HelveticaNeue ;
- path to the font file relative to folder specified in assets-base-path property, e.g. fonts/HelveticaNeue.ttf; note that SDK supports only TTF fonts;
font-size - mandatory parameter, font size measured from base design mockup in points (pt), can be a float value;
font-color, stroke-color - optional, color properties specified in 0xAARRGGBB format;
stroke-size, stroke-offset-x, stroke-offset-y - optional, integer values that should be measured from the base design mockup in pixels.

Font sizes are specified in point

Unlike dimensions, that are specified in pixels (px), font-size property expect values in points (pt).

File name should match postscript name

Font file name should be exactly the same as font postscript name and not file name. Learn how to find postscript name on mac here.

Define text style:

"content": {
    "font": "HelveticaNeue",
    "font-size": 16.0,
    "font-color": "0xFF797E85"
}

Use it for one of the elements:

"content": {
    "text-style": "content"
}

UI Elements Configuration¶

All elements are configured with a set of properties.

Each property can be one of the following types: dimension, color, drawable, text style, insets, paddings, aspect ratio or constant. Type of property is defined by its suffix, e.g. bg-image-normal is a drawable property because it has bg-image suffix.

Check the full list of available properties for elements in the default.json.

Specifying Dimensions¶

Suffixes that correspond to dimension properties: height, width, margin-top, margin-bottom, margin-left, margin-right, text-y-offset-normal, text-y-offset-pressed, radius, border-size, border-radius.

Dimensions are the integer numbers and should be measured from base design mockup in pixels:

"header": {
    "height": 38
}

Specifying Colors¶

Suffixes that correspond to color properties: bg-color, tint-color, bar-color, hint-color, border-color, bg-color-normal, bg-color-pressed, bg-color-even, bg-color-odd, bg-color-read, bg-color-unread, bg-color-selected.

Color properties support alpha and should be specified in 0xAARRGGBB format:

"header": {
    "bg-color": "0xFF2A3B45"
}

Specifying Drawables¶

Suffixes that correspond to drawable properties: bg-image, bg-image-normal, bg-image-selected, bg-image-pressed, default-image.

SDK will load drawables without any configuration if they:

are located in the folder specified in assets-base-path property;
has convention names (original names after executing exportAssets action on assets.psd).

In case you want to use the custom name or reuse the same drawable for several UI elements (e.g., use the same image for several buttons) you have to specify the path to the image relative to the folder specified in assets-base-path property.

For instance, if on Android, you want to use an image located in assets/getsocial/buttons/green-button.png:

"activity-action-button:": {
    "bg-image-normal": "buttons/green-button.png"
}

Specifying Text Style¶

Suffixes that correspond to text style properties: text-style, text-style-normal, text-style-selected.

Text styles configuration consist from two parts: definition in the text-styles block and usage in elements configuration by referencing text style id. Learn how to define a new text style.

To use a text style on the element:

"content": {
    "text-style": "content"
}

Specifying Aspect Ratio¶

A suffix that corresponds to insets properties: aspect-ratio.

Aspect ratio can be specified as a string ("width:height") or a float number (result of division width/height):

"activity-image": {
    "aspect-ratio": "16:9"
}

Specifying Animation Style¶

For now, only window element has animation property.

Supported values for animation-style:

none - window appears without animation
scale - animation scales the window in and out
fade - animation fades the window in and out
fade-and-scale - animation fades and scales the window in and out at the same time

Default animation is set to scale:

"window": {
    "animation-style": "scale"
}

Specifying Fullscreen Window¶

It can happen that you want to display GetSocial Ui fullscreen. You can achieve this by adding fit-parent property to window element:

"window": {
    "width": "fit-parent",
    "height": "fit-parent"
}

Specifying Margin for Window¶

If you want to display some other Ui above or below of GetSocial Ui, use the following properties:

"window": {
    "margin-top": 40
    "margin-bottom": 20
}

Specifying Custom Invite Channel Icons¶

If you want to replace the provided icons for invite channels, use invite-channels-icons entry inside elements, like :

"invite-channels-icons" : {
    // key is a valid invite channel id. For available ids check the following classes:
    // Android: im.getsocial.sdk.invites.InviteChannelIds.java
    // iOS: GetSocialConstants.h
    // Unity: GetSocialSdk.Core.InviteChannelIds
    "facebook" : "custom-facebook-icon.png"
}

The example above replaces the icon for Facebook invite provider.

Give us your feedback! Was this article helpful?

😀 🙁