customize ui easily

Intro

GetSocial SDK is a fully white-label solution, you can easily customize GetSocial views to look and feel natively in your app or game.

UI is configurable with json file and set of custom made assets. To speed up UI customization, SDK goes along with a set of PSD templates with correct named assets slices ready for developers to use after export.

Glossary

Short glossary of the common terms in the UI customization guide:

  • Base design: mockup provided by designer from which all the dimensions are measured;
  • Base resolution: width and height of the base design mockup;
  • Drawable source: image that is used by SDK in the UI;
  • Canvas: screen area that is going to be used to draw the base design.

Designers Guide

All PSD files required for UI customization are included in getsocial-ui-customization.zip archive.

Archive structure

Assets folder

In here you find the assets template PSD, mockups PSD, and all the linked Smart Objects.

Important

Do not change the folder structure otherwise the links will be broken and you will need to relink them one by one!

Tip

Keep assets.psd and mockups.psd both open when editing Smart Object to prevent links to brake and to see changes immediately.

Exports folder

In the exports folder you will find all the sliced assets and mockups exported as png’s. See Exporting assets and mockups section for how to export slices.

Creating assets

If you want to make GetSocial UI look similar to default theme, you can follow basic flow:

ui customization flow

If you want to create unique look and feel of GetSocial views, you can use our mockups as a template, edit the Smart Objects, save & export the slices you want. The visuals will be exported with proper sizes and names.

ui customization flow

assets.psd structure

All the UI elements are Smart Objects located in the links folder. To update Smart Object - double-click on it from assets.psd, make the changes, save the Smart Object and close. Changes to Smart Objects will be updated automatically and showed in assets.psd.

Open assets.psd, go to Layers panel. In the Layers panel you will find the following groups:

ui customization flow

Layer group iconSizes

This group is locked and not visible. By making this group visible, you can see the drawing area/size of the icon that is going to be exported.

Important

Each icon NEEDS to be designed in this area and should not be changed. To avoid modifying them, keep this layer locked!

Layer group insets

This group is locked and visible. This layer group provides the information you need to give to your developers so they can create the stretchable drawable.

This is only required for the chat message bubbles, call to action buttons, and badge.

Tip

Don’t forget to unlock and update the insets according to your design.

Layer group icons

These are all the elements that can be customized.

Use groups and layers names when communicating with the developers implementing the GetSocial SDK. They will know exactly which icon you mean, and they can look for it using the same name if needed in the code.

Important

DO NOT change the names of the layers. These are the same as the slices names and id is the developers are using to configure the SDK.

Layer group background

This group is locked and visible. Don’t forget to turn off this layer when exporting the assets. Assets should be exported as transparent png’s with the predefined slice names.

Tip

If you need more contrast to see your icon designs better, unlock this layer and modify the colors to your preference and lock again.

Slice options

The names of the slices are the id’s used in the SDK.

Editing elements

Make sure your slices are locked before you start editing. To lock the slices in Photoshop go to View > Lock Slices.

To edit an element just double-click to enter the Smart Object and modify it without changing the canvas size. Save and Close when you are done. The icon Smart Object will be will be saved in the links folder and changed automatically in assets.psd and mockups.psd.

Important

DO NOT delete the existing icon or Smart Object.
Always enter the Smart Object and make your design changes in there, save and close.

DO NOT change the Smart Objects individually, this will break the links in assets.psd and mockups.psd.
If changing this make sure you relink the layer after.

Repeat this with the all the elements you want to modify, save, preview them on different views if desired and export the assets or/and the mockups.

Tip

Don’t forget to save in between or turn your autosave on!

Tip

If you are using assets.psd and mockups.psd keep them both open when editing the Smart Objects. This will prevent links breaking and you will be able to see the changes in both psd’s immediately.

Previewing UI

Working with mockups.psd

Open mockups.psd.

Any changes to Smart Objects made in mockups.psd will be automatically saved to files in links folder.

Tip

The size of the UI elements canvas is fixed, so if you want to change a size or position of the element you have to work in the scope of the existing canvas, see example below.

Slice options

The views are already sliced and pre-named. Unlike the assets, you can change the names of the slices if desired.

To export the views check the Exporting assets and mockups section.

Editing elements

Make sure your slices are locked before you start editing (see how to lock slices in Photoshop).

Important

DO NOT forget that the Smart Object canvas size of the icons should NOT be modified (the icons & mockups are the same sizes in both templates). If you resize them in one template, it will not match with expectations of the other one anymore.

Feel free to change the rest of the mockups designs like background colors & fonts-styles according to your app design for a complete mockup design.

After editing and saving the assets in assets.psd, switch to mockups.psd. You will notice that the following Objects didn’t change:

A smaller image, the one in assets.psd, is used to create a nine-patch so we created a separate Smart Object to show the full buttons.

Exporting assets and mockups

To export the views turn off the background layer > Save for Web > click on the Save button > Select folder > on Slice options select All User Slices > click Save.

Tip

After exporting the assets go to http://tinypng.com to compress the files or use the tinypng plugin for photoshop https://tinypng.com/photoshop.

The only thing the developer needs to do is copy the assets and voila!

Important

Do not change the names of the slices. These names are the ones used to configure GetSocial SDK!

Understanding the UI elements sizes

Assets size

Exporting the assets generates 4X/XXXHDPI assets, that is the size expected by the SDK, on the smaller screen size UI elements will be downscaled automatically.

Mockups size and resolution density

Mockups could be designed in any size and density resolution, the developer should put mockup PSD size and resolution density into json configuration file.

photoshop image size settings

Tip

Internally in GetSocial we design mockups with 1280x2560px size and 72ppi resolution density.

Measuring UI elements for json configuration

All the dimension and content padding properties in json configuration should be measured from the base design mockup; on the other hand, drawable insets - from exported assets.

Turning on the dimensions layer will show the guides that correspond to exposed configuration properties.

Measuring dimensions on images with transparent background

In some cases, you need to measure the distance between elements with wholly or partially transparent background, e.g. close button margins should be measured from background window corner. To help with that, all the Smart Objects have extra imgSize layer, that draw red half transparent bound of the available canvas.

To enable it, double-click on the Smart Object > open Layers panel > enable imgSize layer > save > go back to mockpus.psd to check the UI elements with red bounds.

extra imgSize layer

More than one app?

Just duplicate or unzip the getsocial-ui-customization.zip archive again and update the templates with new designs.

Developers Guide

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

There are two approaches how you can customise GetSocial UI look and feel. Recommended way is to use json configuration file, refer to default.json to check default UI configuration. Second option is via methods of GetSocialConfigurationConfigurationConfiguration class, this approach is useful when you want to change UI dynamically from runtime.

In the following sections json configuration file structure will be described, along with a way to change it from runtime.

Providing assets

Inside the project, all the assets (drawables, fonts and configuration) related to GetSocial views have to be placed in one place inside the main bundle under the Resources/ folderunder the assets/ folderunder the Assets/StreamingAssets/ folder.

Getting the configuration instance

All operations with the UI configuration are performerd via GetSocialConfigurationConfigurationConfiguration class and set of properties defined in GetSocialProperty and GetSocialChatProperty structsCoreProperty and ChatProperty classesProperty and ChatProperty classes.

To obtain configuration instance:

GetSocialConfiguration* configuration = [GetSocial sharedInstance].configuration;
var configuration = GetSocialConfiguration.sharedInstance()
Configuration configuration = GetSocial.getConfiguration();
var configuration = GetSocial.Instance.Configuration;
var configuration = GetSocial.Configuration.getInstance();

Loading json configuration

Json configuration should be placed in the main bundle under the Resources/under the assets/under the Assets/StreamingAssets/ folder.

To load configuration from Resources/getsocial/custom_config.jsonassets/getsocial/custom_config.jsonAssets/StreamingAssets/getsocial/custom_config.json call:

NSString *jsonConfigName = @"custom_config";
NSString *jsonConfigPath = @"getsocial";
[configuration setConfiguration:[[NSBundle mainBundle] pathForResource:jsonConfigName ofType:@"json" inDirectory:jsonConfigPath]];
let jsonConfigName = "custom_config"
let jsonConfigPath = "getsocial"
configuration.setConfiguration(NSBundle.mainBundle().pathForResource(jsonConfigName, 
    ofType: "json", 
    inDirectory: jsonConfigPath))
String jsonConfigPath = "getsocial/custom_config.json";
GetSocial.getConfiguration().setConfiguration(jsonConfigPath);
string jsonConfigPath = "getsocial/custom_config.json";
GetSocial.Instance.Configuration.SetConfiguration(jsonConfigPath);
GetSocial.Configuration.getInstance().setConfiguration(fileOrUrl, function(result){}) {
});

Tip

For development purposes setConfigurationsetConfigurationSetConfiguration accepts web urls, so you can put json configuration on a Dropbox (or any other online storage), modify online and reload at runtime without rebuilding the application.

Android Specific


As an alternative if you split application binary during build and obb file is big, for GetSocial load time optimization you can extract content of the obb to the external storage and load configuration from there. Do not forget to add android.permission.READ_EXTERNAL_STORAGE permission to AndroidManifest.xml.

String jsonConfigPath = Environment.getExternalStorageDirectory() + "/getsocial/custom_config.json";
GetSocial.getConfiguration().setConfiguration(jsonConfigPath);
string jsonConfigPath = Application.persistentDataPath + "/getsocial/custom_config.json";
GetSocial.Instance.Configuration.SetConfiguration(jsonConfigPath);

UI configuration transactions

All changes to UI configuration from the code should be done in scope of transaction. Only one transaction could be performed at a time (SDK does not support nested transactions). Any call to GetSocialConfigurationConfigurationConfigurationConfiguration methods (except setConfigurationsetConfigurationSetConfigurationsetConfiguration) outside of transaction will cause assertIllegalStateException exception to be thrown.

Base design

Base design object has a set of properties that describe base design mockup settings and UI behaviour on different screen sizes. GetSocial SDK need to know base design width, height, ppi and scale-mode to calculate UI element sizes on screens with a 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 taken from default.json:

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

To specify base design from the code:

[configuration setBaseDesign:320 height:640 ppi:72 scaleMode:kGetSocialScaleModeScaleWithScreenSize];
configuration.setBaseDesign(320, height: 640, ppi: 72, 
    scaleMode: kGetSocialScaleModeScaleWithScreenSize)
configuration.setBaseDesign(320, 640, 72, GetSocial.SCALE_MODE_SCALE_WITH_SCREEN_SIZE);
configuration.SetBaseDesign(320, 640, 72, GetSocial.ScaleMode.ScaleWithScreenSize);
var width = 320;
var height = 640;
var ppi = 72;
var scaleMode = "scale-with-screen-size";
configuration.setBaseDesign(width, height, ppi, scaleMode);

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/"

To specify base path from the code:

[configuration setBasePath:@"getsocial/"];
configuration.setBasePath("getsocial/")
configuration.setBasePath("getsocial/");
configuration.SetBasePath("getsocial/");
var basePath = "getsocial/";
configuration.setBasePath(basePath);

Android Specific


If you split application binary during build and obb file is big, for GetSocial load time optimization you can extract content of the obb to the external storage and load assets from there. Do not forget to add android.permission.READ_EXTERNAL_STORAGE permission to AndroidManifest.xml.

Note

Absolute path can be specified only from the code.

String basePath = Environment.getExternalStorageDirectory() + "/getsocial/";
configuration.setBasePath(basePath);
string basePath = Application.persistentDataPath + "/getsocial/";
configuration.SetBasePath(basePath);

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 it’s 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
}

To specify dimension from the code:

[configuration setDimension:38 forElementID:GetSocialProperty.HEADER_HEIGHT];
configuration.setDimension(38, 
    forElementID: GetSocialProperty.HEADER_HEIGHT.takeRetainedValue() as String)
configuration.setDimension(CoreProperty.HEADER_HEIGHT, 38);
configuration.SetDimension(Property.HeaderHeight, 38);
var propertyId = "header.height";
var dimension = 38;
configuration.setDimension(propertyId, dimension);

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"
}

To specify color property from the code:

[configuration setColor:[UIColor colorWithARGBHex:0xFF2A3B45] forElementID:GetSocialProperty.HEADER_BG_COLOR];
configuration.setColor(UIColor(red: 0.5, green: 0.5, blue: 0.5, alpha: 1.0), 
    forElementID: GetSocialProperty.HEADER_BG_COLOR.takeRetainedValue() as String)
configuration.setColor(CoreProperty.HEADER_BG_COLOR, 0xFF2A3B45);
configuration.SetColor(Property.HeaderBgColor, 0xFF2A3B45);
var propertyId = "header.bg-color";
var color = "0xFF2A3B45";
configuration.setColor(propertyId, color);

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:

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

Fo instance to use image located in Resources/getsocial/buttons/green-button.pngassets/getsocial/buttons/green-button.pngAssets/StreamingAssets/getsocial/buttons/green-button.png:

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

To specify custom drawable from the code:

[configuration setImagePath:@"buttons/green-button.png" forElementID:GetSocialProperty.INVITE_FRIENDS_BUTTON_BG_IMAGE_NORMAL];
configuration.setImagePath("buttons/green-button.png", 
    forElementID: GetSocialProperty.INVITE_FRIENDS_BUTTON_BG_IMAGE_NORMAL.takeRetainedValue()
     as String)

You also have the option to replace the images inside the GetSocial.bundle directly to avoid including the default images in your final build. If you decide to do this, make sure that you replace files with the same name, extension, and resolution.

configuration.setImagePath(CoreProperty.INVITE_FRIENDS_BUTTON_BG_IMAGE_NORMAL, "buttons/green-button.png");
configuration.SetImagePath(Property.InviteFriendsButtonBgImageNormal, "buttons/green-button.png");
var propertyId = "invite-friends-button.bg-image-normal";
var path = "path/to/image";
configuration.setImagePath(propertyId, path);

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.

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:

Important

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

Important

Font file name should be exactly the same as font postscript 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"
}

Unlike json configuration, in the code text style is defined and applied at the same time:

[configuration setTextStyle:@"HelveticaNeue" fontSize:16f fontColor:[UIColor colorWithARGBHex:0xFF797E85] forElementID:GetSocialProperty.CONTENT_TEXT_STYLE];
configuration.setTextStyle("HelveticaNeue", fontSize: 16f,
    fontColor: UIColor(red: 0.5, green: 0.5, blue: 0.5, alpha: 1.0),
    forElementID: GetSocialProperty.CONTENT_TEXT_STYLE.takeRetainedValue() as String)
configuration.setTextStyle(CoreProperty.CONTENT_TEXT_STYLE, "HelveticaNeue", 16, 0xFF797E85);
configuration.SetTextStyle(Property.ContentTextStyle, "HelveticaNeue", 16f, 0xFF797E85);
var propertyId = "content.text-style";
var fontName = "HelveticaNeue";
var textSize = 16;
var textColor = "0xFF797E85";
var strokeColor = "0xFF797E85";
var strokeSize = 0;
var strokeXOffset = 0;
var strokeYOffset = 0;
configuration.setTextStyle(propertyId, fontName, textSize, textColor, strokeColor, strokeSize, strokeXOffset, strokeYOffset);

Specifying insets

Suffixes that correspond to insets properties: bg-image-normal-insets, bg-image-insets, bg-image-pressed-insets.

Insets is a way to define images that automatically resize to accommodate the contents of the view and the size of the screen. Selected parts of the image are scaled horizontally or vertically based on specified insents (similar to 9-patch drawable).

Insets should are an integers; should be measured from drawable sources in pixels (not base design mockup) and put into a json configuration in order: “top right bottom left” inset:

"my-chat-message": {
    "bg-image-normal": "my-chat-message.bg-image-normal.png",
    "bg-image-normal-insets": "44 116 54 44"
}

To specify the drawable insets from code:

[configuration setInsets:44 right:116 bottom:54 left:44 forElementID:GetSocialChatProperty.MY_CHAT_MESSAGE_BG_IMAGE_NORMAL];
configuration.setInsets(44, right: 116, bottom: 54, left: 44, 
    forElementID: GetSocialChatProperty.MY_CHAT_MESSAGE_BG_IMAGE_NORMAL.takeRetainedValue()
    as String)
configuration.setInsets(ChatProperty.MY_CHAT_MESSAGE_BG_IMAGE_NORMAL, 44, 116, 54, 44);
configuration.SetInsets(ChatProperty.MyChatMessageBgImageNormal, 44, 116, 54, 44);
var propertyId = "my-chat-message.bg-image-normal";
var top = 44;
var right = 116;
var bottom = 54;
var left = 44;
configuration.setInsets(propertyId, top, right, bottom, left);

Specifying paddings

A suffix that correspond to insets properties: text-insets.

Paddings (or text-insets) define the relative area within the image that the contents of the view are allowed to lie within.

In the mockup above, the dark area identifies the region in which the contents of the view are allowed. If the contents do not fit in this region, then the image will be stretched so that they do.

Paddings are an integer numbers and should be measured from base design mockup in pixels, order in the json configuration: “top right bottom left”:

"my-chat-message": {
    "text-insets": "8 26 8 8"
}

Important

Unlike drawable insets, that should be measured from the source file, paddings should be measured from base design mockup.

To specify the content paddings from code:

[configuration setInsets:8 right:26 bottom:8 left:8 forElementID:GetSocialChatProperty.MY_CHAT_MESSAGE_BG_IMAGE_NORMAL_INSETS];
configuration.setInsets(8, right: 26, bottom: 8, left: 8, 
    forElementID: GetSocialChatProperty.MY_CHAT_MESSAGE_BG_IMAGE_NORMAL_INSETS.takeRetainedValue()
    as String)
configuration.setInsets(ChatProperty.MY_CHAT_MESSAGE_BG_IMAGE_NORMAL_INSETS, 8, 26, 8, 8);
configuration.SetInsets(ChatProperty.MyChatMessageBgImageNormalInsets, 8, 26, 8, 8);
var propertyId = "my-chat-message.bg-image-normal-insets";
var top = 8
var right = 26;
var bottom = 8;
var left = 8;
configuration.setInsets(propertyId, top, right, bottom, left);

Specifying aspect ratio

A suffix that correspond 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"
}

or

"activity-image": {
    "aspect-ratio": 1.7777
}

To specify the aspect ratio from code:

[configuration setAspectRatio:16/9 forElementID:GetSocialProperty.ACTIVITY_IMAGE_ASPECT_RATIO];
configuration.setAspectRatio(16/9, 
    forElementID: GetSocialProperty.ACTIVITY_IMAGE_ASPECT_RATIO.takeRetainedValue() as String)
configuration.setAspectRatio(CoreProperty.ACTIVITY_IMAGE_ASPECT_RATIO, 16f/9f);
configuration.SetAspectRatio(Property.ActivityImageAspectRatio, 16f/9f);
var propertyId = "activity-image.aspect-ratio";
var aspectRatio = 16/9;
configuration.setAspectRatio(propertyId, aspectRatio);

Specifying animation style

For now only window element has animation property.

Supported values for animation-style:

Default animation is set to scale:

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

To specify the animation style from code:

[configuration setAnimationStyle:GetSocialAnimationStyleScale forElementID:GetSocialProperty.WINDOW_ANIMATION_STYLE];
configuration.setAnimationStyle(.Scale, 
    forElementID: GetSocialProperty.WINDOW_ANIMATION_STYLE.takeRetainedValue() as String)
configuration.setAnimationStyle(CoreProperty.WINDOW_ANIMATION_STYLE, GetSocial.ANIMATION_SCALE);
configuration.SetAnimationStyle(Property.WindowAnimationStyle, GetSocial.AnimationStyle.Scale);
var propertyId = "window.animation-style";
var animationStyle = "scale";
configuration.setAnimationStyle(propertyId, animationStyle);