Getting Started

Build and manage the community within your apps with GetSocial.

GetSocial provides the whole social layer stack that powers engagement, retention, acquisition and revenue tools.

Features Include:

Minimum system requirements:

  • Xcode 7 or above
  • iOS 7 or higher
  • Android v4.0.3 (SDK v15) or higher
  • Android Developers Tools (ADT) version 19 or above
  • Google Play Services library v6.1.11 or above (for push notifications)
  • Unity 4.6 or above
  • To deploy on Android:

    • Android v4.0.3 (SDK v15) or higher
    • Android Developers Tools (ADT) version 19 or above
    • Google Play Services library v6.1.11 or above (for push notifications)
  • To deploy on iOS:

    • Xcode 7 or above
    • iOS 7 or higher
  • Apache Cordova 5.4.1 or above
  • To deploy on Android:

    • Android v4.0.3 (SDK v15) or higher
    • Android Developers Tools (ADT) version 19 or above
    • Google Play Services library v6.1.11 or above (for push notifications)
  • To deploy on iOS:

    • Xcode 7 or above
    • iOS 7 or higher

For more information on GetSocial, visit our website or contact us.

To manage the integration of the GetSocial SDK, login to the GetSocial Dashboard.

Adding GetSocial to your app

GetSocial SDK consists of two modules: GetSocial and GetSocialChat.

GetSocial contains all available features(Activities, SmartInvites and Notifications) except chat, and it can be used as a standalone framework.
On the other hand, GetSocialChat cannot be used as a standalone framework, and it should always link with GetSocial.

Now, let’s add both modules to your project.

Using Cocoapods

Cocoapods is a dependency manager for ObjectiveC that will make it easy to add and update GetSocial SDK.

  1. Install Cocoapods: sudo gem install cocoapods

  2. Close your Xcode project and use the terminal to navigate to your project’s directory.

  3. If you don’t have one already, make a new file called Podfile with no extension: touch Podfile

  4. Add the GetSocial SDK to your Podfile

    platform :ios, "7.0"
    pod "GetSocial"
    

    Alternatively, if you only want to install the GetSocial and not GetSocialChat module:

    platform :ios, "7.0"
    pod "GetSocial/Core"
    

    Change the deployment target in the podfile if is different from the one you defined in your project.

  5. Install the SDK: pod install

  6. Make sure that from now one, you open the workspace (.xcworkspace) instead of the project (.xcodeproj)

Manually

Download the latest GetSocial iOS SDK from the GitHub.

Open your App on Xcode and drag and drop the GetSocial.embeddedframework folder into your project navigator.

Make sure you select “Create groups” option while adding the folder.

Now you have the basic features that GetSocial provides.

If you want to add the chat functionality you can do this by drag and drop the GetSocialChat.embeddedframework folder into your project navigator.

Make sure your project structure ends up looking like this:

Manual integration

You also need to ensure that you include in the “Link Binary with Libraries” the following iOS Native Frameworks

  • Accelerate.framework
  • AdSupport.framework
  • AVFoundation.framework
  • CFNetwork.framework
  • CoreFoundation.framework
  • CoreGraphics.framework
  • CoreImage.framework
  • CoreTelephony.framework
  • CoreText.framework
  • Foundation.framework
  • MessageUI.framework
  • MobileCoreServices.framework
  • QuartzCore.framework
  • Security.framework
  • Social.framework
  • SystemConfiguration.framework
  • UIKit.framework

and these libraries

  • libicucore.tbd
  • libsqlite3.tbd

Finally just add this flag -ObjC to your project’s “Other Linker Flags” inside Build Settings section.

Using Swift?

GetSocialSDK is written in Objective-C, so to be able to use it in your Swift project you have to create a bridging header as described here: Using Swift with Cocoa and Objective-C

GetSocial SDK consists of two modules: GetSocial and GetSocialChat.

GetSocial contains all available features(Activities, SmartInvites and Notifications) except chat, and it can be used as a standalone framework.
On the other hand, GetSocialChat cannot be used as a standalone framework, and it should always link with GetSocial.

Now, let’s add both modules to your project.

Using Gradle

GetSocial Android SDK jars are available via our maven repository. To use the GetSocial SDK in your project add reference to our repository and compile dependency to GetSocial to your build.gradle:

repositories {
    maven { url  "http://getsocial-im.bintray.com/maven" }
    mavenCentral()
}

dependencies {
    compile 'im.getsocial:android-sdk-core:5.+'
    compile 'im.getsocial:android-sdk-chat:5.+' // here you can add chat module if you want to use it
    compile 'com.google.code.gson:gson:2.5'
}

All GetSocial dependencies (google gson) will be resolved automatically.

Check the latest available version at Bintray.

Manually

Download the latest GetSocial Android SDK from the GitHub.

  • Create a directory called libs in your project, if it does not exist already.
  • Copy the core module from the bin/ folder of downloaded repo into the libs directory and, optionally, copy the chat module as well if you will be using chat functionality.
  • Add reference(s) to the jar(s) in build.gradle.
dependencies {
    compile fileTree(dir: 'libs/', include: '*.jar')
}

Libraries Method Count and Size

As it is important to keep method count below 65K here are method counts for GetSocial libraries as for Android version v5.1.4 (Unity v5.1.4):

  • getsocial-android-sdk-core-v5.1.4.jar - 7801 methods (around 1.5 MB)
  • getsocial-android-sdk-chat-v5.1.4.jar - 1004 methods (around 200 KB)
  • GetSocial also has dependency on gson version 2.6.2 which has 1329 methods (around 250 KB)

These numbers are not going to change much in future versions.

Download the latest GetSocial Unity SDK from the GitHub.


  1. In Unity Editor, go to Assets → Import Package → Custom Package… and select GetSocial.unitypackage. Import all files from the package.
  2. If you are using Unity 5, after importing GetSocial.unitypackage into the project Unity will prompt you to upgrade the project. Click "I made a Backup. Go Ahead!" button and the API updater will update all the GetSocial code automatically.
  3. Sync MonoDevelop Project
  4. Open GetSocial Editor, go to GetSocial → Edit Settings
  5. Select what modules are you going to use
  6. Press green Fix it button to configure the project

Android Specific

Libraries Method Count and Size

As it is important to keep method count below 65K here are method counts for GetSocial libraries as for Android version v5.1.4 (Unity v5.1.4):

  • getsocial-android-sdk-core-v5.1.4.jar - 7801 methods (around 1.5 MB)
  • getsocial-android-sdk-chat-v5.1.4.jar - 1004 methods (around 200 KB)
  • GetSocial also has dependency on gson version 2.6.2 which has 1329 methods (around 250 KB)

These numbers are not going to change much in future versions.

Manifest Configuration

To run on Android, you need to modify your AndroidManifest.xml file. If you do not have AndroidManifest.xml yet, copy the one provided in the demo project.

Starting from v4.0.0 GetSocial Unity SDK does not require overwriting the UnityPlayerActivity.

The following permissions are required for the core functionality to work:

<!--INTERNET permission is required to communicate with GetSocial API-->
<uses-permission android:name="android.permission.INTERNET"/>
<!--ACCESS_NETWORK_STATE permission is required to handle network connectivity changes-->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

Android Manifest Checker

Some GetSocial features require extra AndroidManifest.xml configuration. For this purpose we have created Android Manifest Checker. You can find it under GetSocial settings in AndroidManifest.xml Settings section.

Important

Editor will analyze and modify only the AndroidManifest.xml file and will not add or modify any libraries in your project.

image alt text

Path to manifest

By default the checker will look for your manifest file in Plugins/Android folder. If your main manifest is in another folder, find AndroidManifestHelper.cs and modify the MainManifestPath constant to point to you main manifest.

Running demo

  1. Open DemoScene located in GetSocial Demo/Scenes/ folder
  2. For Android, to be able to use Facebook login, configure app signing with provided get-social-debug.keystore
    1. Go to Edit → Project Settings → Player
    2. Select Android section and go to Publishing Settings category
    3. Browse to select provided keystore, located in GetSocial Demo/ folder
    4. Keystore password: android, key alias: androiddebugkey, key password: android
  3. For iOS everything is working out of the box, just don’t forget to create appropriate provision profile
  4. Build demo, go to File → Build & Run

Manually Download the latest GetSocial Cordova Plugin from the GitHub.

Using npmjs Install the plugin from npmjs:

npm i getsocial-cordova-sdk

Add plugin to your Apache Cordova application:

cordova plugin add im.getsocial.sdk.cordova --variable APP_ID={FB_APP_ID} --variable APP_NAME={FB_APP_NAME} --variable GOOGLE_APP_ID={GOOGLE_APP_ID}

If you want to use Facebook Smart Invites, provide FB_APP_ID and FB_APP_NAME variables.
If you want to use Google Plus Sign-In, provide GOOGLE_APP_ID variable.

Initialization

In just a few steps, you will be able to have your app GetSocial-ready. Once you have the basics in place, you can easily add other GetSocial features into your App.

To start with, you need to create an App on the GetSocial Dashboard and copy App Key from App Information section or obtain the key from your GetSocial Developers Relations Manager.

Before using any other functionality, you should first initialize the GetSocial SDK:

Add GetSocial.h to your AppDelegate.m if you are using ObjC or Bridging-Header.h file if you are using Swift:

// AppDelegate file
#import <GetSocial/GetSocial.h>
// Bridging header file
#import <GetSocial/GetSocial.h>

And call the initWithKey: inside application:didFinishLaunchingWithOptions:

[[GetSocial sharedInstance] initWithKey:@"[YOUR_APP_KEY]" success:^{
  // GetSocial SDK initialized
} failure:^(NSError *error) {
  // GetSocial SDK not initialized
}];
GetSocial.sharedInstance().initWithKey("[YOUR_APP_KEY]", success: { () -> Void in
  //GetSocial Initialization succeded
}, failure: { (error: NSError!) -> Void in
  //GetSocial initialization failed
})

You can also register an observer to be notified every time one of our views is opened or closed.

[[GetSocial sharedInstance] setOnWindowStateChangedHandler:^(BOOL isOpen) {
        if (isOpen)
        {
            //code to handle the opening of a GetSocial View, maybe pause the App if needed.
        }
        else
        {
            //code to handle the closing of a GetSocial View, maybe resume the App if needed.
        }
    }];
GetSocial.sharedInstance().setOnWindowStateChangedHandler { (isOpen : Bool) -> Void in
    if (isOpen) {
        //code to handle the opening of a GetSocial View, maybe pause the App if needed.
    } else {
        //code to handle the closing of a GetSocial View, maybe resume the App if needed.
    }
}

First of all, you need to modify your AndroidManifest.xml file for GetSocial to run correctly, by adding the following permissions.

<!--INTERNET permission is required to communicate with GetSocial API-->
<uses-permission android:name="android.permission.INTERNET"/>
<!--ACCESS_NETWORK_STATE permission is required to handle network connectivity changes-->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

Before using any other functionality, you should first initialize the GetSocial SDK:

GetSocial getSocial = GetSocial.getInstance();
getSocial.init(getApplicationContext(), "[YOUR_APP_KEY]", new GetSocial.OperationObserver()
{
    @Override
    public void onSuccess(String data)
    {
        // GetSocial SDK initialized
    }

    @Override
    public void onFailure(String errorMessage)
    {
        // GetSocial SDK not initialized
    }
});

The GetSocial SDK should be notified every time the Activity that contains the View(s) that build up your App is paused or resumed.

Here’s how you do it:

@Override
protected void onResume()
{
    super.onResume();
    getSocial.onResume(this);
}

@Override
protected void onPause()
{
    super.onPause();
    getSocial.onPause();
}

To make the back button interaction work with the GetSocial SDK UI you also need to override the onBackPressed as follow:

@Override
public void onBackPressed()
{
    if(!getSocial.handleBackButtonPressed())
    {
        super.onBackPressed();
    }
}

You can also register a listener to be notified every time the GetSocial window is opened or closed.

getSocial.setOnWindowStateChangeListener(new GetSocial.OnWindowStateChangeListener()
{
    @Override
    public void onOpen()
    {
        //code to handle the opening of a GetSocial View, maybe pause the App if needed.
    }

    @Override
    public void onClose()
    {
        //code to handle the closing of a GetSocial View, maybe resume the App if needed.
    }
});

Proguard Configuration

If you have custom proguard configuration for you project include the lines below

-keepattributes Signature,InnerClasses,Annotation
-keepattributes SourceFile,LineNumberTable
-keepattributes *Annotation*
-keepclassmembers enum * {
    public static **[] values();
    public static ** valueOf(java.lang.String);
}

-dontwarn java.beans.**
-dontwarn java.awt.**
-dontwarn javax.swing.**
-dontwarn javax.xml.**
-keep class javax.xml.** {*;}

-dontwarn com.google.**
-keep class com.google.** {*;}

-dontwarn android.support.**

-keep public class android.support.v7.widget.** { *; }
-keep public class android.support.v7.internal.widget.** { *; }
-keep public class android.support.v7.internal.view.menu.** { *; }

-keep public class * extends android.support.v4.view.ActionProvider {
    public <init>(android.content.Context);
}

-dontwarn im.getsocial.**
-keep class im.getsocial.** {*;}
-keepnames class im.getsocial.** {*;}

-dontwarn com.unity3d.**
-keep class com.unity3d.** {*;}

-dontwarn org.apache.**
-keep class org.apache.** {*;}

-dontwarn sun.misc.Unsafe
-keep class sun.misc.Unsafe { *; }
-keep class com.google.gson.stream.** { *; }

-keep class thirdparty.wamp.** { *; }
-keepnames class thirdparty.wamp.** { *; }

-dontwarn com.facebook.**
-keep class com.facebook.** {*;}

Before using any other functionality, you should first initialize the GetSocial SDK:

Go to GetSocial → Edit Settings and fill the GetSocial App Key field. Right after that you can initialize SDK from code:

var getSocial = GetSocial.Instance;
getSocial.Init(
    () => { /* GetSocial SDK initialized */ },
    () => { /* GetSocial SDK initialization failed */ }
);

As an alternative to specifying key in the editor, you can pass it as a first parameter of the Init:

getSocial.Init(
    key: "[YOUR_APP_KEY]",
    () => { /* GetSocial SDK initialized */ },
    () => { /* GetSocial SDK initialization failed */ }
);

You can also register a listener to be notified every time one of the GetSocial views is opened or closed.

getSocial.SetOnWindowStateChangeListener(
    onOpen: () => { /* code to handle the opening of a GetSocial View, maybe pause the App if needed. */ },
    onClose: () => { /* code to handle the closing of a GetSocial View, maybe resume the App if needed. */ }
);

Important

GetSocial SDK uses native Android and iOS libraries, so it is not possible to test it in the Unity Editor, where all method calls are mocked.

GetSocial.init('App Key',
        function(){
            // GetSocial SDK initialized
        }, function(errorMessage){
            // GetSocial SDK not initialized
        });

Upgrade guide

Migration from version 4.x to version 5.0

On GetSocial SDK 5.0 we’ve rebuilt and improved most of the features, making it even easier to start using and integrating them into your app.

If you’ve already integrated GetSocial SDK 4.x or earlier, you will need to update some calls to make them compatible with the new SDK version.

User Management was considerably improved, allowing you to safely use your own custom authentication method and keep use your existing IDs. We introduced concept of anonymous users that can interact with GetSocial SDK. You can now also change display name and avatar with a simple call.

We suggest you read through the User Management section to understand how this impacts your current integration.

Chat was completely rebuilt, client and server side, making it even more reliable and ready to scale to the infinite!

Although calls from the GetSocial SDK remain the same, unfortunately, chatting between users with 4.x and 5.x is not possible.

Users using GetSocial SDK 4.x will see a localized message asking them to update your app, when trying to open a chat with a user using 5.x.
On the other side, users using GetSocial SDK 5.x will see a localized message informing that the other user needs to update the app.

It was a hard decision to make, but the new Chat platform opens up much more flexibility and we are working to make all that flexibility available for you!

Problems with integration?

Please don’t hesitate to contact us if you have any problems trying to update your integration.
We will happily assist you right away.

User Management

As soon as you initialize the GetSocial SDK for the first time, an anonymous user will be created, ready to interact with all the features.

GetSocial SDK allows you to identify your users by adding User Identities for any identity provider.

An Identity Provider could be any service that provides authenticated users to your app, for example, Facebook, Google+ or even your own authentication method.

A User identity is a combination of Provider Id and a User Id that allows you to identify the users easily inside the SDK without the need to create, or store, IDs of users other than the ones you are already using in your app.

For example, if you identify users in your app with Facebook, you can add a Facebook identity to the GetSocial user and keep using the Facebook Id to interact with any of the features of the SDK.

If you have a proprietary login method for your users, you can add a custom identity and keep using the same Id you already use inside your app.

The GetSocial user is persistent across session, that means that anything you set up for this user, will be still available the next time the user opens your app and our SDK gets initialized. There is no need to add identities each time.

Anonymous users

An anonymous user is a user that doesn’t have any added identity and therefore cannot be recovered from a different device.

By default, a random display name (i.e. User_1234567890) and a default avatar will be set, which you can overwrite.

The user will remain anonymous until you add the first identity.

By default, anonymous users can interact with all the features on the GetSocial SDK without any limitations.

If you want to limit the actions that an anonymous user can perform on the GetSocial SDK, please refer to Intercepting Actions.

To check if the user is anonymous:

GetSocialCurrentUser *user = [GetSocial sharedInstance].currentUser;

if (user.isAnonymous) {
    //User doesn't have any identities
}
let user = GetSocial.sharedInstance().currentUser

if (user.isAnonymous) {
    // User doesn't have any identities
}
User user = GetSocial.getInstance().getCurrentUser();
if (user.isAnonymous())
{
    // User doesn't have any identities
}
var user = GetSocial.Instance.CurrentUser;
if (user.IsAnonymous)
{
   // User doesn't have any identities
}
GetSocial.getCurrentUser(function(currentUser) {
    if(currentUser.isAnonymous()){
        // User doesn't have any identities
    }
});

Adding identities for Social Networks

You can add identities for social networks. Currently GetSocial supports Facebook and Google+.

For Facebook we will retrieve the user’s list of friends and import them so that it can be used later through our Friend list feature.

To be able to add identities for these providers, you need to provide the token you get from their SDKs when the user authenticates.

Don’t forget to sync the display name and avatar of the GetSocial user with the values from the added social network identity.

FBSDKLoginManager *login = [FBSDKLoginManager new];
[login
    logInWithReadPermissions:kGetSocialAuthPermissionsFacebook
    fromViewController:self
    handler:^(FBSDKLoginManagerLoginResult *result, NSError *error) {

        if (!error && !result.isCancelled)
        {
            GetSocialUserIdentity *identity = [GetSocialUserIdentity
                                                facebookIdentityWithToken:result.token.tokenString];

            [[GetSocial sharedInstance].currentUser addUserIdentity:identity
                complete:^(GetSocialAddIdentityResult result) {
                    //AddIdentity was completed, check result to see
                    //if identity was added or conflict was resolved
                }
                failure:^(NSError *error) {
                    //An error occurred while adding the user identity
                    //Check if the token provided is valid
                }
                conflict:^(GetSocialUser *currentUser, GetSocialUser *remoteUser,
                    void (^resolve)(GetSocialAddIdentityConflictResolutionStrategy strategy)) {
                    //There is a conflict because this Facebook Identity was
                    //already added to another user and needs to be resolved
                }];
        }
    }];
}
let login = FBSDKLoginManager()
login.logInWithReadPermissions(["email", "user_friends"],
    fromViewController: self) { (result : FBSDKLoginManagerLoginResult!, error : NSError!) -> Void in

    if(error == nil && !result.isCancelled){

        let identity = GetSocialUserIdentity.facebookIdentityWithToken(result.token.tokenString)
        GetSocial.sharedInstance().currentUser.addUserIdentity(identity,
        complete: { (result: GetSocialAddIdentityResult) -> Void in
            //AddIdentity was completed, check result to see
            //if identity was added or conflict was resolved
        }, failure: { (error: NSError!) -> Void in
            // An error occured while adding the user identity
            // Check if the token provided is valid
        }, conflict: { (currentUser : GetSocialUser!,
                        remoteUser : GetSocialUser!,
                        strategy : ((GetSocialAddIdentityConflictResolutionStrategy) -> Void)!) -> Void in
            // There is a conflict because this Facebook Identity was
            // already added to another user and needs to be resolved
        })
    }
}
FacebookSdk.sdkInitialize(getApplicationContext());
final AccessTokenTracker accessTokenTracker = new AccessTokenTracker()
{
    @Override
    protected void onCurrentAccessTokenChanged(AccessToken oldAccessToken, AccessToken newAccessToken)
    {
        stopTracking();

        UserIdentity fbIdentity = UserIdentity.createWithFacebookToken(newAccessToken.getToken());
        GetSocial.getInstance().getCurrentUser().addUserIdentity(
                fbIdentity,
                new AddUserIdentityObserver()
                {
                    @Override
                    public void onComplete()
                    {
                        // Identity was successfully added
                    }

                    @Override
                    public void onError(Exception error)
                    {
                        // An error occured while adding the user identity
                        // Check if the token provided is valid
                    }

                    @Override
                    public void onConflict(User currentUser, User remoteUser, UserIdentityResolver resolver)
                    {
                        // There is a conflict because this Facebook Identity was
                        // already added to another user and needs to be resolved
                    }
                }
        );
    }
};
accessTokenTracker.startTracking();

LoginManager.getInstance().logInWithReadPermissions(this, Arrays.asList("email", "user_friends"));
// this example uses Facebook Unity SDK version 6.2.2
FB.Init(() =>
{
    FB.Login("public_profile,user_friends",
        result =>
        {
            if (string.IsNullOrEmpty(result.Error))
            {
                var identity = UserIdentity.CreateFacebookIdentity(FB.AccessToken);
                GetSocial.Instance.CurrentUser.AddUserIdentity(identity,
                    result =>
                    {
                        // AddIdentity was completed, check result to see
                        // if identity was added or conflict was resolved
                    },
                    error =>
                    {
                        // An error occurred while adding the user identity
                        // Check if the token provided is valid
                    },
                    (currentUser, remoteUser, resolveAction) =>
                    {
                        // There is a conflict because this Facebook Identity was
                        // already added to another user and needs to be resolved
                    });
            }
        });
});
facebookConnectPlugin.login(["email", "user_friends"],
    function(userData) {
        facebookConnectPlugin.getAccessToken(function(token) {
            GetSocial.getCurrentUser(function(currentUser) {
                currentUser.addFbUserIdentity(token, function(user) {
                        // AddIdentity was completed, check result to see
                        // if identity was added or conflict was resolved
                    }, function() {
                        // There is a conflict because this Facebook Identity was
                        // already added to another user and needs to be resolved
                    }, function(error) {
                        // An error occurred while adding the user identity
                        // Check if the token provided is valid
                    });
        });
    , function (error) {
        onError(error);
    });
});

To understand better the concept of a User Identity conflict, please refer to Recovering Users.

Adding identities for Custom Providers

If you have a proprietary login method that you already use on your App or any other provider that we don’t currently support natively (i.e. Game Center, Twitter, etc.), you can also identify your users with it.

In this case, you will need to provide a Provider Id, a User Id and a Token.

The Provider Id is a unique string identifier of the provider, e.g. “twitter”, “custom_auth_method”.
The User Id is the unique string identifier of the user on the specified provider.
The Token is a custom string, linked to the user, that you will need to provide to be able to recover this user later, if needed.

To login with the same user on several devices, you have to provide the same combination of Provider Id / User Id / Token.

We suggest to build the Token using a hash of the User Id and a shared secret.
This way, you can easily regenerate the token if the user adds the identity on another device.

After adding the custom identity, you will also need to set the display name and avatar for the user.


NSString *userId = @"1234567";
NSString *token = [[NSString stringWithFormat:@"%@-%@", userId, @"[SHARED_SECRET]"] MD5];

//Check this category to create a MD% hash from string:
//http://stackoverflow.com/questions/2018550/how-do-i-create-an-md5-hash-of-a-string-in-cocoa

GetSocialUserIdentity *identity = [GetSocialUserIdentity
                                      identityWithProvider:@"[CUSTOM_PROVIDER_ID]"
                                      userId:userId
                                      token:token];

[[GetSocial sharedInstance].currentUser addUserIdentity:identity
    complete:^(GetSocialAddIdentityResult result) {
        //AddIdentity was completed, check result to see
        //if identity was added or conflict was resolved
    }
    failure:^(NSError *error) {
        //An error occurred while adding the user identity
        //Check if the token provided is valid
    }
    conflict:^(GetSocialUser *currentUser, GetSocialUser *remoteUser,
        void (^resolve)(GetSocialAddIdentityConflictResolutionStrategy strategy)) {
        //There is a conflict because this Custom Identity was
        //already added to another user and needs to be resolved
    }];
let userId = "1234567"
let token = "\(userId)-\([[SHARED_SECRET] MD5])"

let identity = GetSocialUserIdentity(provider: "\([CUSTOM_PROVIDER_ID])",
    userId : userId,
    token: token)

GetSocial.sharedInstance().currentUser.addUserIdentity(identity,
    complete: { (result: GetSocialAddIdentityResult) -> Void in
        //AddIdentity was completed, check result to see
        //if identity was added or conflict was resolved
    }, failure: { (error: NSError!) -> Void in
        //An error occurred while adding the user identity
        //Check if the token provided is valid
    }, conflict: { (currentUser : GetSocialUser!, remoteUser : GetSocialUser!,
            resolve : ((GetSocialAddIdentityConflictResolutionStrategy) -> Void)!) -> Void in
                //There is a conflict because this Custom Identity was
                //already added to another user and needs to be resolved
})
String userId = "1234567";
String token = SomeCustomUtils.MD5(String.format("%s-%s", userId, "[SHARED_SECRET]"));
UserIdentity identity = UserIdentity.create("[CUSTOM_PROVIDER_ID]", userId, token);
GetSocial.getInstance().getCurrentUser().addUserIdentity(identity, new AddUserIdentityObserver()
{
    @Override
    public void onComplete(AddIdentityResult identityResult)
    {
        // Identity was successfully added
    }

    @Override
    public void onError(Exception error)
    {
        // An error occurred while adding the user identity
        // Check if the token provided is valid
    }

    @Override
    public void onConflict(User currentUser, User remoteUser, UserIdentityResolver resolver)
    {
        // There is a conflict because this Facebook Identity was
        // already added to another user and needs to be resolved
    }
});
string userId = @"1234567";
string token = string.Format("{0}={1}", userId, "[SHARED_SECRET]").MD5();

UserIdentity identity = UserIdentity.Create("[CUSTOM_PROVIDER_ID]", userId, token);
GetSocial.Instance.CurrentUser.AddUserIdentity(identity,
    result =>
    {
        // AddIdentity was completed, check result to see
        // if identity was added or conflict was resolved
    },
    error =>
    {
        // An error occurred while adding the user identity
        // Check if the token provided is valid
    },
    (currentUser, remoteUser, resolveAction) =>
    {
        // There is a conflict because this Facebook Identity was
        // already added to another user and needs to be resolved
    });
GetSocial.getCurrentUser(function(currentUser) {
    currentUser.addUserIdentity("userId", "token", function(user){
            // AddIdentity was completed, check result to see
            // if identity was added or conflict was resolved
        }, function(){
            // There is a conflict because this identity was
            // already added to another user and needs to be resolved
        }, function(error){
            // An error occurred while adding the user identity
            // Check if the token provided is valid
    }, function (error) {
        // could not get current user
    });
});

To understand better the concept of a User Identity conflict, please refer to Recovering Users.

Important

Do not use password from your proprietary login system as a Token if you provide a way to change the password to the user. Token can not be changed, so after changing the password you won’t be able to recover this user anymore.

Recovering users

A quite common scenario is that your users change devices or want to use your app on several devices at the same time, and of course, they might want to keep using the same user on all devices.

You can easily recover a user by adding, to the current GetSocial user, the same identity that you already added to the user on the first device.

Let’s look into particular use case.

You identify users in the app with Facebook. Linda, a new user, has just authenticated with Facebook and you’ve added the Facebook identity to the GetSocial user.

After some time, Linda gets a new device and wants to continue using your app there.

She will open the app and will authenticate again with Facebook to get back her user. In this moment, you will need to add the Facebook identity to the current anonymous GetSocial user on this new device.

When you do that, SDK will detect that the identity already belongs to an existing GetSocial user and raise an identity conflict callback that you can easily resolve with either the Current User, the GetSocial user currently on the device, or with the Remote User, the user Linda had on the first device.

The user you choose to resolve the conflict with will be the one available as GetSocial current user.

If you are using a custom provider to identify your users, the flow is exactly the same.

FBSDKLoginManager *login = [FBSDKLoginManager new];
[login
    logInWithReadPermissions:kGetSocialAuthPermissionsFacebook
    fromViewController:self
    handler:^(FBSDKLoginManagerLoginResult *result, NSError *error) {

        if (!error && !result.isCancelled)
        {
            GetSocialUserIdentity *identity = [GetSocialUserIdentity
                                                  facebookIdentityWithToken:result.token.tokenString];

            [[GetSocial sharedInstance].currentUser addUserIdentity:identity
                complete:^(GetSocialAddIdentityResult result) {
                    //AddIdentity was completed, check result to see
                    //if identity was added or conflict was resolved
                }
                failure:^(NSError *error) {
                    //An error occurred while adding the user identity
                    //Check if the token provided is valid
                }
                conflict:^(GetSocialUser *currentUser, GetSocialUser *remoteUser,
                    void (^resolve)(GetSocialAddIdentityConflictResolutionStrategy strategy)) {
                    //There is a conflict because this Identity was
                    //already added to Linda's users on the first device.
                    resolve(GetSocialAddIdentityConflictResolutionStrategyRemote);
                }];
        }
    }];
}
let login = FBSDKLoginManager()
login.logInWithReadPermissions(["email", "user_friends"],
    fromViewController: self) { (result : FBSDKLoginManagerLoginResult!, error : NSError!) -> Void in

    if(error == nil && !result.isCancelled){

        let identity = GetSocialUserIdentity.facebookIdentityWithToken(result.token.tokenString)

        GetSocial.sharedInstance().currentUser.addUserIdentity(identity,
        complete: { (result: GetSocialAddIdentityResult) -> Void in
            //AddIdentity was completed, check result to see
            //if identity was added or conflict was resolved
        }, failure: { (error: NSError!) -> Void in
            // An error occured while adding the user identity
            // Check if the token provided is valid
        }, conflict: { (currentUser : GetSocialUser!, remoteUser : GetSocialUser!,
                resolve : ((GetSocialAddIdentityConflictResolutionStrategy) -> Void)!) -> Void in
                    //There is a conflict because this Identity was
                    //already added to Linda's users on the first device.
                    resolve(.Remote)
        })
    }
}
FacebookSdk.sdkInitialize(getApplicationContext());
final AccessTokenTracker accessTokenTracker = new AccessTokenTracker()
{
    @Override
    protected void onCurrentAccessTokenChanged(AccessToken oldAccessToken, AccessToken newAccessToken)
    {
        stopTracking();

        UserIdentity fbIdentity = UserIdentity.createWithFacebookToken(newAccessToken.getToken());
        GetSocial.getInstance().getCurrentUser().addUserIdentity(
                fbIdentity,
                new AddUserIdentityObserver(AddIdentityResult identityResult)
                {
                    @Override
                    public void onComplete()
                    {
                        // Identity was successfully added
                    }

                    @Override
                    public void onError(Exception error)
                    {
                        // An error occured while adding the user identity
                        // Check if the token provided is valid
                    }

                    @Override
                    public void onConflict(User currentUser, User remoteUser, UserIdentityResolver resolver)
                    {
                        // There is a conflict because this Facebook Identity was
                        // already added to another user and needs to be resolved
                        resolver.resolve(AddIdentityConflictResolutionStrategy.USE_REMOTE);
                    }
                }
        );
    }
};
accessTokenTracker.startTracking();

LoginManager.getInstance().logInWithReadPermissions(this, Arrays.asList("email", "user_friends"));
// this example uses Facebook Unity SDK version 6.2.2
FB.Init(() =>
{
    FB.Login("public_profile,user_friends",
        result =>
        {
            if (string.IsNullOrEmpty(result.Error))
            {
                var identity = UserIdentity.CreateFacebookIdentity(FB.AccessToken);

                GetSocial.Instance.CurrentUser.AddUserIdentity(identity,
                    result =>
                    {
                        // AddIdentity was completed, check result to see
                        // if identity was added or conflict was resolved
                    },
                    error =>
                    {
                        // An error occurred while adding the user identity
                        // Check if the token provided is valid
                    },
                    (currentUser, remoteUser, resolveAction) =>
                    {
                        // There is a conflict because this Identity was
                        // already added to Linda's users on the first device.
                        resolveAction(CurrentUser.AddIdentityConflictResolutionStrategy.UseRemote);
                    });
            }
        });
});
var facebookInvitePlugin = new GetSocial.FacebookInvitePlugin();
facebookConnectPlugin.login(["email", "user_friends"],
    function(userData) {
        facebookConnectPlugin.getAccessToken(function(token) {
            GetSocial.getCurrentUser(function(currentUser) {
                currentUser.addFbUserIdentity(token, function(user, result){
                        // AddIdentity was completed, check result to see
                        // if identity was added or conflict was resolved
                    }, function() {
                        // There is a conflict because this Identity was
                        // already added to Linda's users on the first device.
                        // We resolve conflict with remote user, which means user from the first device
                        currentUser.resolveUserIdentityConflict("remote");
                    }, function(error) {
                        // An error occurred while adding the user identity
                        // Check if the token provided is valid
                    });
                });
            }, function (error) {
                // could not get current user
            });
        });
    });
If the `conflict` callback is not specified, it will be resolved with **Remote User** by default.

At the end of the addIdentity operation, either the complete or the failure callback will be executed.

The complete callback will be called when:

These 3 cases can be identified using the `result` parameter inside the `complete` callback.

The failure callback will be called when:

This might make things even more clear for you:

Add Identity flow

Changing display name and avatar

You can change the display name and/or avatar for the GetSocial user at anytime.
Provided display name and avatar will be displayed on activities, comments, chats or any other interaction by the user.

To change the display name of the GetSocial user:

[[GetSocial sharedInstance].currentUser setDisplayName:@"[NEW_DISPLAY_NAME]"
    success:^{
        //Display name was successfully changed
    }
    failure:^(NSError *error) {
        //There was an error changing the display name
    }];
GetSocial.sharedInstance().currentUser.setDisplayName("[NEW_DISPLAY_NAME]",
    success: { () -> Void in
        // Display name was successfully changed
    }, failure: { (error : NSError!) -> Void in
        // There was an error changing the display name
})
GetSocial.getInstance().getCurrentUser().setDisplayName("[NEW_DISPLAY_NAME]", new CurrentUser.UpdateUserInfoObserver()
{
    @Override
    public void onComplete()
    {
        // Display name was successfully changed
    }

    @Override
    public void onError(Exception error)
    {
        // There was an error changing the display name
    }
});
GetSocial.Instance.CurrentUser.SetDisplayName("NEW_DISPLAY_NAME",
    () =>
    {
        // Display name was successfully changed
    },
    error =>
    {
        // There was an error changing the display name
    });
GetSocial.getCurrentUser(function(currentUser) {
        currentUser.setDisplayName("NEW_DISPLAY_NAME", function(newName){
            // Display name was successfully changed
        }, function(error) {
            // There was an error changing the display name
        });
    }, function (error) {
        // could not get current user
    });

To change the avatar url:

[[GetSocial sharedInstance].currentUser setAvatarUrl:@"[NEW_AVATAR_URL]"
    success:^{
        //Avatar was successfully changed
    }
    failure:^(NSError *error) {
        //There was an error changing the avatar url
    }];
GetSocial.sharedInstance().currentUser.setAvatarUrl("[NEW_AVATAR_URL]",
    success: { () -> Void in
        //Avatar was successfully changed
    }) { (error : NSError!) -> Void in
        //There was an error changing the avatar url
}
GetSocial.getInstance().getCurrentUser().setAvatarUrl("[NEW_AVATAR_URL]", new CurrentUser.UpdateUserInfoObserver()
{
    @Override
    public void onComplete()
    {
        // Avatar was successfully changed
    }

    @Override
    public void onError(Exception error)
    {
        // There was an error changing the avatar
    }
});
GetSocial.Instance.CurrentUser.SetAvatarUrl("NEW_AVATAR_URL",
    () =>
    {
        // Avatar was successfully changed
    },
    error =>
    {
        // There was an error changing the avatar
    });

Are you compiling with iOS 9?

You need to make sure that the urls of the avatars you use is either https or the domain you are using is added as an exception on the info.plist according to the new App Transport Security.

GetSocial.getCurrentUser(function(currentUser) {
        currentUser.setAvatarURL("NEW_AVATAR_URL", function(newAvatarURL){
            // Avatar was successfully changed
        }, function(error) {
            // There was an error changing the avatar
        });
    }, function (error) {
        // could not get current user
    });

Retrieving user information

You can retrieve the current GetSocial user information, like GUID, avatar url, display name, and added identities.

GUID stands for GetSocial User Id, it is unique user identifier in GetSocial.

GetSocialUserIdentity *user = [GetSocial sharedInstance].currentUser;
let user = GetSocial.sharedInstance().currentUser
CurrentUser user = GetSocial.getInstance().getCurrentUser();
var user = GetSocial.Instance.CurrentUser;
GetSocial.getCurrentUser(function(currentUser) {
        // current user returned
    }, function (error) {
        // could not get current user
    });

To check whether the user has identity for the specified provider

BOOL hasFacebookIdentity = [[GetSocial sharedInstance].currentUser
    hasIdentityForProvider:kGetSocialProviderFacebook];
let hasFacebookIdentity = GetSocial.sharedInstance().currentUser.
    hasIdentityForProvider(kGetSocialProviderFacebook)
boolean hasFacebookIdentity = GetSocial.getInstance().getCurrentUser().hasIdentityForProvider(UserIdentity.PROVIDER_FACEBOOK);
bool hasFacebookIdentity = GetSocial.Instance.CurrentUser.HasIdentityForProvider(UserIdentity.ProviderFacebook);
var providerId = "facebook";
GetSocial.getCurrentUser(function(currentUser) {
            var identities = currentUser.getIdentities();
            for(var i=0; i < identities.length; i++) {
                if(identities[i] === providerId){
                    // provider found
                }
            }
    }, function (error) {
        // could not get current user
    });

Removing identities

You can remove an identity you have previously added to the GetSocial user.

Please keep in mind that after removing an identity, you won’t be able to identify this user anymore with the Provider Id / User Id combination you’ve just removed.

After removing all identities for the GetSocial user, it will become anonymous.

Anonymous users can not be transferred to a different device.

The user’s display name and avatar will remain the same.

[[GetSocial sharedInstance].currentUser
    removeUserIdentityForProvider:kGetSocialProviderFacebook
    success:^{
        //Identity was successfully removed
    }
    failure:^(NSError *error) {
        //There was an error removing this identity
    }];
GetSocial.sharedInstance().currentUser.removeUserIdentityForProvider(kGetSocialProviderFacebook,
    success: { () -> Void in
        //Identity was successfully removed
    }, failure: { (error: NSError!) -> Void in
        //There was an error removing this identity
})
GetSocial.getInstance().getCurrentUser().removeUserIdentity(UserIdentity.PROVIDER_FACEBOOK, new CurrentUser.UpdateUserInfoObserver()
{
    @Override
    public void onComplete()
    {
        // Identity was successfully removed
    }

    @Override
    public void onError(Exception error)
    {
        // There was an error removing this identity
    }
});
GetSocial.Instance.CurrentUser.RemoveUserIdentity(UserIdentity.ProviderFacebook,
    () =>
    {
        // Identity was successfully removed
    },
    error =>
    {
        // There was an error removing this identity
    });
GetSocial.getCurrentUser(function(currentUser) {
        currentUser.removeUserIdentity("facebook",function(user){
            // Identity was successfully removed
        }, function(error) {
            // There was an error removing this identity
        })
    }, function (error) {
        // could not get current user
    });

Resetting the user

Most likely, you will only need to reset the GetSocial user when your user logs out from your app.

[[GetSocial sharedInstance].currentUser
    resetWithSuccess:^{
        //User was successfully resetted
    }
    failure:^(NSError *error) {
        //There was an error resetting the user
    }];
GetSocial.sharedInstance().currentUser.resetWithSuccess({ () -> Void in
        //User was successfully resetted
    }) { (error : NSError!) -> Void in
        //There was an error resetting the user
}
GetSocial.getInstance().getCurrentUser().reset(new CurrentUser.UpdateUserInfoObserver()
{
    @Override
    public void onComplete()
    {
        // User was successfully resetted
    }

    @Override
    public void onError(Exception error)
    {
        // There was an error resetting the user
    }
});
GetSocial.Instance.CurrentUser.Reset(
    () =>
    {
        // Identity was successfully removed
    },
    error =>
    {
        // There was an error removing this identity
    });
GetSocial.getCurrentUser(function(currentUser) {
        currentUser.reset(function(user) {
            // User was successfully resetted
        }, function(error) {
            // There was an error resetting the user
        })
    }, function (error) {
        // could not get current user
    });

Resetting the user means generating a new anonymous user .

The identities, display name, avatar and all the interactions from the previous user won’t be affected and the user can be still recovered.

Important

Keep in mind that if you reset an anonymous user you will never able to recover this user again and all associated data (activity posts, chat messages) will be lost.

Activities

The Activities feature in the GetSocial SDK allows you to create timelines where users can post and get likes and comments.

Likes and comments can be sent as Push Notifications or can be seen on the Notification Center.

Users and you, as a developer, can post questions, tips, news, promotions and easily interact with others.

For promotions, you can show images and even add an action button to do anything you want, when user clicks on it.

You can also have a global activity feed or do any kind of segmentation like Levels, Clans, Countries, etc.

Showing Global Activities

Showing the activities view is quite easy

[[[GetSocial sharedInstance] createActivitiesView] show];
GetSocial.sharedInstance().createActivitiesView().show()
getSocial.createActivitiesView().show();
getSocial.CreateActivitiesView().Show();
var activitiesView = new GetSocial.ActivitiesViewBuilder();
activitiesView.show();

You can also customize the view by adding a custom title

GetSocialActivitiesViewBuilder *viewBuilder = [[GetSocial sharedInstance] createActivitiesView];
[viewBuilder setTitle:@"Level 1"];
[viewBuilder show];
let viewBuilder : GetSocialActivitiesViewBuilder = GetSocial.sharedInstance().createActivitiesView()
viewBuilder.title = "Level 1"
viewBuilder.show()
getSocial.createActivitiesView().setTitle("Level 1").show();
getSocial.CreateActivitiesView().SetTitle("Level 1").Show();
var activitiesView = new GetSocial.ActivitiesViewBuilder();
activitiesView.setTitle("Level 1");
activitiesView.show();

Showing Segmented Activities

We also provide a flexible way to segment activities and be able to show what you want, where you want it.

This is done by providing groups and tags when creating the activities’ view.

A group contains a set of tags and basically can be used to define the location where you are showing the activities.
Imagine you want to have a different Activity feed per Level in your game, but on the main screen you want to show the activities from all the levels combined.

To achieve this scenario, you will have to go to the GetSocial Dashboard and create 1 group and 1 tag per Level (i.e. level1), adding each tag to the corresponding group.

You will need to also create a group for the main screen (i.e. main) and you will need to include inside all the tags you’ve created before for the levels.

Finally, in your app, you will need to make this call to open activities per level:

[[[GetSocial sharedInstance] createActivitiesViewWithGroup:@"level1" andTags:@[@"level1"]] show];
GetSocial.sharedInstance().createActivitiesViewWithGroup("level1",
    andTags: ["level1"]).show()
getSocial.createActivitiesView("level1", Arrays.asList("level1")).show();
getSocial.CreateActivitiesView("level1", "level1").Show();
var group = "level1";
var tag = "level1";
var activitiesView = new GetSocial.ActivitiesViewBuilder(group, tag).show();

And for the main screen, you will need to add this:

[[[GetSocial sharedInstance] createActivitiesViewWithGroup:@"main" andTags:@[@"main"]] show];
GetSocial.sharedInstance().createActivitiesViewWithGroup("main",
    andTags: ["main"]).show()
getSocial.createActivitiesView("main", Arrays.asList("main")).show();
getSocial.CreateActivitiesView("main", "main").Show();
var group = "level_1";
var tag = "level_1";
var activitiesView = new GetSocial.ActivitiesViewBuilder(group, tag).show();

The group parameter will filter only activities that have any of the tags that were included in that group on the GetSocial Dashboard.

The tags parameter (one or many) are the tags that are going to be set to all activities created through the view that you are creating.

Do you need help to segment your activity feeds?

Do you need more control on what to show on the Activity Feed or maybe have different Activity feeds per level, per clan or a custom attribute? Contact us and we will show you how to do it easily.

Posting Activities

You can also post different activities directly from the app on behalf of the logged in user.

Posted activities can include text, image, button and an action. For more information about the action see “Handling Actions”.

[[GetSocial sharedInstance] postActivity:@"I have just bought an extra life"
    withImage:[UIImage imageNamed:@"lifepromo.png"]
    buttonText:@"Get one!"
    action:@"buy-extra-life"
    andTags:nil success:^{
        // activity was posted successfully
    } failure:^(NSError *error) {
        // A generic error occurred or the user was not authenticated
    }];
GetSocial.sharedInstance().postActivity("I have just bought an extra life",
    withImage: UIImage(named: "lifepromo.jpg"),
    buttonText: "Get one!",
    action: "buy-extra-life",
    andTags: nil,
    success: { () -> Void in
        // activity was posted successfully
    }) { (error : NSError!) -> Void in
        // a generic error occured or the user was not authenticated
    }
getSocial.postActivity("I have just bought an extra life",
                imageByteArray,
                "Get one!",
                "buy-extra-life",
                null,
                new GetSocial.OperationObserver()
                {
                    @Override
                    public void onSuccess(String data)
                    {
                        // Activity was posted successfully
                    }

                    @Override
                    public void onFailure()
                    {
                        // A generic error occurred or the user was not authenticated
                    }
                }
        );
getSocial.PostActivity(
    text: "I have just bought an extra life",
    image: Resources.Load<Texture2D>("lifepromo").EncodeToPNG(),
    buttonText: "Get one!",
    actionId: "buy-extra-life",
    tags: null,
    (data) => { /* Activity was posted successfully */ },
    () => { /* A generic error occurred or the user was not authenticated */}
);
var activityText = "I have just bought an extra life";
var imageURL = "url/to/image";
var buttonText = "Get one!";
var actionId = "buy-extra-life";
GetSocial.postActivity(activityText,imageURL, buttonText, actionId, function(){
        // activity was posted successfully
    }, function(error){
        // A generic error occurred or the user was not authenticated
    });

Handling Actions

The action is a value that will be forwarded to the app when the user clicks on any activity that was posted with an action button.

The value of the action is a string that could be, for example, an internal link to a particular screen or an InApp Purchase item, a link to an external website, or anything that makes sense for your app.

For handling actions in activities you will need to define a block to handle that:

[[GetSocial sharedInstance] setActivityActionClickHandler:^(NSString *action) {
    // Custom code to handle the received action
}];
GetSocial.sharedInstance().setOnActivityActionClickHandler { (action : String!) -> Void in
    // custom code to handle the received action
}
getSocial.setOnActivityActionClickListener(new GetSocial.OnActivityActionClickListener()
{
    @Override
    public void onActivityActionClick(String action)
    {
        // Custom code to handle the received action
    }
});
getSocial.SetOnActivityActionClickListener((actionId) => {
    // Custom code to handle the received action
});
GetSocial.setOnActivityActionClickListener(function(isManualProcessed, actionId) {
    // Custom code to handle the received action
});

Smart Invites

Using Smart Invites users can easily invite their friends to join and use the app. To open the smart invite view you should call:

[[[GetSocial sharedInstance] createSmartInviteView] show];
GetSocial.sharedInstance().createSmartInviteView().show()
getSocial.createSmartInviteView().show();
getSocial.CreateSmartInviteView().Show();
var smartInviteView = new GetSocial.SmartInviteViewBuilder().show();

You will see several options to invite friends, depending on what applications you have currently installed on your device and which providers you enabled on the GetSocial Dashboard.

In case you decide to implement your own UI for smart invites, we expose methods to get the list of supported invite providers on a current device and perform invitation with a specific provider.

You can also attach any custom data inside the Smart Invite. This data will be accessible by the receiver of the Smart Invite once the app is installed, if it was not before, or open if it was already on the device.

Referral data is a dictionary of key-value pairs

NSDictionary *referralData = @{@"level":@1,
    @"stars":@20,
    @"reward":@YES,
    @"source":@"topRightButton"};
let referralData = ["level":1,
    "stars":20,
    "reward":true,
    "source":"topRightButton"]
Map<String, String> referralData = new HashMap<String, String>();
referralData.put("level", "1");
referralData.put("stars", "20");
referralData.put("reward", "true");
referralData.put("source", "topRightButton");
var referralData = new Dictionary<string, string>() {
    { "level", "1" },
    { "stars", "20" },
    { "reward", "true" },
    { "source", "topRightButton"}
};
var referralData = {"level":1,
                    "stars":20,
                    "reward":true,
                    "source":"topRightButton"}

Use this dictionary to invite friends programmatically

NSMutableDictionary *properties = [[NSMutableDictionary alloc] init];
properties[kGetSocialSubject] = @"A subject";
properties[kGetSocialText] = [NSString stringWithFormat:@"A message with %@", kGetSocialAppInviteUrlPlaceholder];
properties[kGetSocialImage] = [UIImage imageNamed:@"Image"];
properties[kGetSocialReferralData] = referralData;

[[GetSocial sharedInstance] inviteFriendsUsingProvider:kGetSocialProviderWhatsapp withProperties:properties];
var properties = Dictionary<NSObject, AnyObject>()
properties[kGetSocialSubject] = "A subject"
properties[kGetSocialText] = "A message with \(kGetSocialAppInviteUrlPlaceholder)"
properties[kGetSocialImage] = UIImage(named: "Image")
properties[kGetSocialReferralData] = referralData

GetSocial.sharedInstance().inviteFriendsUsingProvider(kGetSocialProviderWhatsapp, withProperties: properties)
getSocial.inviteFriendsUsingProvider("whatsapp", subject, text, image, referralData);
getSocial.InviteFriendsUsingProvider(
    provider: "whatsapp",
    subject: "Check this app",
    text: string.Format("A message with {0}", GetSocial.AppInviteUrlPlaceholder),
    image: Resources.Load<Texture2D>("invite").EncodeToPNG(),
    referralData: referralData
);
GetSocial.inviteFriendsUsingProvider("whatsapp", "check this app", "Sample text", "inviteImage.jpg", referralData, function(onResult){
    });

Alternatively, show the provided GetSocial invite UI to the user

GetSocialSmartInviteViewBuilder *viewBuilder = [[GetSocial sharedInstance] createSmartInviteView];
[viewBuilder setSubject:@"A subject"];
[viewBuilder setText:[NSString stringWithFormat:@"A message with %@", kGetSocialAppInviteUrlPlaceholder];];
[viewBuilder setImage:[UIImage imageNamed:@"Image"]];
[viewBuilder setReferralData:referralData];

[viewBuilder show];
var viewBuilder = GetSocial.sharedInstance().createSmartInviteView()
viewBuilder.subject = "A subject"
viewBuilder.text = "A message with \(kGetSocialAppInviteUrlPlaceholder)"
viewBuilder.image = UIImage(named: "Image")
viewBuilder.referralData = referralData
viewBuilder.show()
getSocial.createSmartInviteView()
    .setSubject("A subject")
    .setText("A message with " + GetSocial.PLACEHOLDER_APP_INVITE_URL)
    .setReferralData(referralData)
    .show();
getSocial.CreateSmartInviteView()
    .SetSubject("Check this app")
    .SetText(string.Format("A message with {0}", GetSocial.AppInviteUrlPlaceholder))
    .SetImage(Resources.Load<Texture2D>("invite").EncodeToPNG())
    .SetReferralData(referralData)
    .Show();
var smartInviteView = new GetSocial.SmartInviteViewBuilder();
smartInviteView.setTitle("Invitation Title")
smartInviteView.setSubject("Invitation Subject - [APP_INVITE_URL]")
smartInviteView.setImagePath("/www/img/activityImage.png")
smartInviteView.setReferralData(referralData)
smartInviteView.show();

Smart Invite text can be customized with special tags

When you are overriding the Smart Invites text from the code, you can use those tags to customize the message. That also means that Invite URL will not be appended automatically to the invite.

  • kGetSocialAppInviteUrlPlaceholderGetSocial.PLACEHOLDER_APP_INVITE_URLGetSocial.AppInviteUrlPlaceholder[APP_INVITE_URL]: Replaced with URL to download the app.
  • kGetSocialAppNamePlaceholderGetSocial.PLACEHOLDER_APP_NAMEGetSocial.AppNamePlaceholder[APP_NAME]: Replaced with app name configured on the GetSocial Dashboard.
  • kGetSocialUserDisplayNamePlaceholderGetSocial.PLACEHOLDER_USER_DISPLAY_NAMEGetSocial.UserDisplayNamePlaceholder[USER_DISPLAY_NAME]: Replaced with the user display name. Use only if the user is logged in.
  • kGetSocialAppIconUrlPlaceholderGetSocial.PLACEHOLDER_APP_ICON_URLGetSocial.AppIconUrlPlaceholder[APP_ICON_URL]: Replaced with the app icon URL.
  • kGetSocialAppPackageNamePlaceholderGetSocial.PLACEHOLDER_APP_PACKAGE_NAMEGetSocial.AppPackageNamePlaceholder[APP_PACKAGE_NAME]: Replaced with the app package name.

Are you compiling with iOS 9?

Since iOS 9, Apple requires apps to specify which URL schemes will be used inside the app.
The GetSocial SDK uses Url schemes to interact with some of the Smart Invite providers, therefore you will need to add them by using the LSApplicationQueriesSchemes array in your Xcode project’s Info.plist file.
Add whatsapp, line, kik-share and kakaolink as a string in this array.


GetSocial Unity SDK does not add these schemes by default because we are not sure which ones you are going to use. Please refer to DemoAppIOSPostprocess.cs postprocess file that adds all the required schemes to the test app, you can adjust it to your needs and reuse.

For more info refer to Apple documentation.

Android Specific

If you want to attach an image to the smart invite(e.g. Email, Twitter), you have to declare the following content provider in your app manifest.

<provider
        android:name="im.getsocial.sdk.core.provider.ImageContentProvider"
        android:authorities="YOUR_PACKAGE_NAME.smartinvite.images.provider"
        android:exported="true"/>

Important

Don’t forget to replace YOUR_PACKAGE_NAME with your application package

Supported media types

On a GetSocial Dashboard, it is possible to configure default Smart Invite subject, text, and attached image. Some of the providers support all features, some not. In the table below you can find the clarification of features supported by different providers.

Provider Custom subject Custom text Custom image
Email + + +
Line - + +
Twitter - + +
SMS - + +
Messenger - + +
WhatsApp - + -
Kik - + -
Kakao - + -
Facebook - - -

Inviting through Facebook

You can enable the Smart Invites for Facebook by registering our invite plugin.

We provide a basic Facebook plugin that you can use in your app. Check it out in the plugins folderplugins folderplugins folder on our GitHub repository. Don’t forget to call Facebook init method before the invite is sent.

Facebook Android SDK compatibility

GetSocial SDK and provided Invite Provider plugins are compatible with Facebook Android SDK 4.x (Facebook SDK 3.x is not supported anymore)

We provide a basic Facebook plugin that you can use on your app. Check the plugins folder inside the example application.

//Register FBInvitePlugin
GetSocialFacebookInvitePlugin *fbInvitePlugin = [[GetSocialFacebookInvitePlugin alloc] init];
[[GetSocial sharedInstance] registerPlugin:fbInvitePlugin provider:kGetSocialProviderFacebook];
let fbInvitePlugin = GetSocialFacebookInvitePlugin()
GetSocial.sharedInstance().registerPlugin(fbInvitePlugin, provider: kGetSocialProviderFacebook)
getSocial.registerPlugin(UserIdentity.PROVIDER_FACEBOOK, new FacebookInvitePlugin(this, CallbackManager.Factory.create()));

The loginWithFacebook method is the same you use to authenticate users with Facebook, and we explained before and it is required to be able to authenticate users with Facebook before showing the invite UI. You can find the script implementation in GetSocialSDK Demo/Scripts/ folder.

You can enable the Smart Invites for Facebook by registering FacebookInvitePlugin provided with demo scene.

App Invites vs App Requests

If you are using Facebook Unity SDK v7.+ it is highly recommended to use App Invites instead of App Requests because we are unable to track the app install in case of app requests. Use this plugin code as an example of using App Invites in Unity 5+ and Facebook Unity SDK v7.+

getSocial.RegisterPlugin(UserIdentity.ProviderFacebook, new FacebookInvitePlugin(LoginWithFacebook));

You can enable the Smart Invites for Facebook by registering FacebookInvitePlugin:

var facebookInvitePlugin = new window.GetSocialTestApp.FacebookInvitePlugin();
GetSocial.registerPlugin(function(data) {
    // fb plugin registered
    }, facebookInvitePlugin);

Registering plugins

You must call Facebook SDK Activate App Method once your application becomes active for App Invites track install events working properly.

To enable install tracking call the App Events logger once your application becomes active:

@Override
protected void onResume() {
  super.onResume();
  AppEventsLogger.activateApp(this);
  // ...
}

// Optional: App Deactivation Event
@Override
protected void onPause() {
  super.onPause();
  AppEventsLogger.deactivateApp(this);
}

To enable install tracking call the App Events once your application becomes active:

- (void)applicationDidBecomeActive:(UIApplication *)application {
   [FBSDKAppEvents activateApp];
}

Registering plugins

All plugins must be registered before GetSocial initialization.

Inviting through Custom plugins

You can enable the Smart Invites for Facebook Messenger and KakaoTalk by registering our invite plugins.

We provide a basic custom plugins that you can use in your app. Check it out in the plugins folderplugins folderplugins folder on our GitHub repository.

You can register the Facebook Messenger plugin by

//Register FBMessenger InvitePlugin
GetSocialFBMessengerInvitePlugin *fbMessengerPlugin = [[GetSocialFBMessengerInvitePlugin alloc] init];
[[GetSocial sharedInstance] registerPlugin:fbMessengerPlugin provider:kGetSocialProviderFacebookMessenger];
let fbMessengerPlugin = GetSocialFBMessengerInvitePlugin()
GetSocial.sharedInstance().registerPlugin(fbMessengerPlugin, provider: kGetSocialProviderFacebookMessenger)

You can register the Facebook Messenger plugin by

getSocial.registerPlugin(FacebookMessengerInvitePlugin.PROVIDER_NAME, new FacebookMessengerInvitePlugin());

Important

The link is supported without the message text.

You can enable the Smart Invites for Facebook by registering FacebookMessengerInvitePlugin provided with demo scene.

getSocial.RegisterPlugin(FacebookMessengerInvitePlugin.ProviderName, new FacebookMessengerInvitePlugin());

Important

The link is supported without the message text.
We currently support Facebook Messenger on Unity only with Android. Please contact us to find out more.

You can register the KakaoTalk plugin with the following code

//Register Kakao InvitePlugin
GetSocialKakaoTalkInvitePlugin *kakaoPlugin = [[GetSocialKakaoTalkInvitePlugin alloc] init];
[[GetSocial sharedInstance] registerPlugin:kakaoPlugin provider:kGetSocialProviderKakao];
let kakaoPlugin = GetSocialKakaoTalkInvitePlugin()
GetSocial.sharedInstance().registerPlugin(kakaoPlugin, provider: kGetSocialProviderKakao)

Important

Please note that you need to add http://sm.getsocial.im or your custom invite domain as Site Domain in your Kakao Dashboard.

You can register the KakaoTalk plugin with the following code

getSocial.registerPlugin(KakaoInvitePlugin.PROVIDER_NAME, new KakaoInvitePlugin());

Important

Please note that you need to add http://sm.getsocial.im or your custom invite domain as Site Domain in your Kakao Dashboard.

KakaoTalk is coming soon…

Registering plugins

All plugins must be registered before GetSocial initialization.

Inviting using system share dialog

Starting from version 5.1 GetSocial SDK supports sending Smart Invites via system share dialog. In GetSocial UI and a Dashboard the system share option is called “More”. You can enable or disable invite provider from the GetSocial Dashboard.

More Invite

Install tracking

iOS Specific

Install Tracking attribution on iOS is done automatically by the GetSocial SDK.
The only requirement for the flow to work is to have Deep Linking set up correctly.

Android Specific

To allow the GetSocial SDK to track new installations you have to declare the InstallReferrerReceiver in your Manifest as follow.

<receiver
    android:name="im.getsocial.sdk.core.gms.InstallReferrerReceiver">
    <intent-filter>
        <action android:name="com.android.vending.INSTALL_REFERRER" />
    </intent-filter>
</receiver>

You have to have the Google Play Services enabled in your Manifest and reference the Google Play services library project:

<meta-data
    android:name="com.google.android.gms.version"
    android:value="@integer/google_play_services_version"/>

Or if you are using gradle:

apply plugin: 'com.android.application'
    ...

    dependencies {
        compile 'com.google.android.gms:play-services:8.1.0'
    }

Multiple install tracker receivers

When Android application is installed on the device, only a single receiver will get the referrer data. If GetSocial is the only receiver tracking installs than you don’t need to do anything after adding it to manifest.

However, if you want to process referrer data on your own or pass it to another third party library, you have to create your own receiver, add it to your manifest and call onReceive method manually on all other receivers:

public class MasterInstallTrackerReceiver extends BroadcastReceiver {
    @Override
    public void onReceive(Context context, Intent intent) {
        InstallReferrerReceiver getSocialInstallTracker = new InstallReferrerReceiver();
        getSocialInstallTracker.onReceive(context, intent);

        // Do the same with other receivers or process referrer data
    }
}

Now add this “master” receiver to your AndroidManifest.xml:

<receiver
    android:name="YOUR_PACKAGE_NAME.MasterInstallTrackerReceiver"
    android:exported="true">
    <intent-filter>
        <action android:name="com.android.vending.INSTALL_REFERRER" />
    </intent-filter>
</receiver>

You can broadcast the same intent that the Google Play Store application broadcasts to your application after it is installed by a user.
To test whether the intent is received correctly you can run ADB shell command to broadcast the install intent and check whether it is intercepted.

adb shell am broadcast -a com.android.vending.INSTALL_REFERRER -n YOUR_PACKAGE_NAME/im.getsocial.sdk.core.GetSocialReceiver –-es "referrer" "utm_source=test_source&utm_medium=emma&utm_term=test_term&utm_content=test_content&utm_campaign=666"

For more information check the official Google documentation

Referral data

To retrieve the custom data embedded to the Smart Invite you need to register for a callback:

[[GetSocial sharedInstance] setOnReferralDataReceivedHandler:^(NSArray *referralDataArray) {
    if(referralDataArray.count > 0)
    {
        NSDictionary * referralData = referralDataArray[0];

        NSString * inviteToken = referralData[@"$id"];
        NSString * inviteProviderId = referralData[@"$provider"];
        NSString * isFirstMatch = referralData[@"$first_match"];
        NSString * referrerUserGetSocialId = referralData[@"referrer_user_guid"];
        NSString * referrerUserIdfa = referralData[@"$referrer_idfa"];

        // All custom data attached to the invite 
        // is also available via referralData dictionary
        NSString * customValue1 = referralData[@"custom_key_1"];
        NSString * customValue2 = referralData[@"custom_key_2"];
    }
}];
GetSocial.sharedInstance().setOnReferralDataReceivedHandler { (referralDataArray : [AnyObject]!) -> Void in
  if referralDataArray.count > 0 {
    var referralData = referralDataArray[0]
    var inviteToken = referralData["$id"]
    var inviteProviderId = referralData["$provider"]
    var isFirstMatch = referralData["$first_match"]
    var referrerUserGetSocialId = referralData["referrer_user_guid"]
    var referrerUserIdfa = referralData["$referrer_idfa"]

    // All custom data attached to the invite 
    // is also available via referralData dictionary
    var customValue1 = referralData["custom_key_1"]
    var customValue2 = referralData["custom_key_2"]
  }
}
getSocial.setOnReferralDataReceivedListener(new GetSocial.OnReferralDataReceivedListener()
{
  @Override
  public void onReferralDataReceived(List<Map<String, String>> referralDataArray)
  {
    if(!referralDataArray.isEmpty())
    {
      Map<String, String> referralData = referralDataArray.get(0);

      String inviteToken = referralData.get("$id");
      String inviteProviderId = referralData.get("$provider");
      String isFirstMatch = referralData.get("$first_match");
      String referrerUserGetSocialId = referralData.get("referrer_user_guid");
      String referrerUserIdfa = referralData.get("$referrer_idfa");

      // All custom data attached to the invite 
      // is also available via referralData map
      String customValue1 = referralData.get("custom_key_1");
      String customValue2 = referralData.get("custom_key_2");
    }
  }
});

To make Smart Invite feature properly working be also sure to have the Google Play Services enabled in your Manifest:

<meta-data
    android:name="com.google.android.gms.version"
    android:value="@integer/google_play_services_version"/>
getSocial.SetOnReferralDataReceivedListener((referralData) => {
  if(referralDataList != null && referralDataList.Count > 0) {
      Dictionary<String, String> referralData = referralDataList[0];

      String inviteToken = referralData["$id"];
      String inviteProviderId = referralData["$provider"];
      String isFirstMatch = referralData["$first_match"];
      String referrerUserGetSocialId = referralData["referrer_user_guid"];
      String referrerUserIdfa = referralData["$referrer_idfa"];

      // All custom data attached to the invite 
      // is also available via referralData dictionary
      String customValue1 = referralData["custom_key_1"];
      String customValue2 = referralData["custom_key_2"];
  }
});

Android Specific In order for deep linking to work correctly and to be able to receive the referral data correctly you have to declare the following activity in your app manifest:

<activity android:name="im.getsocial.sdk.core.unity.GetSocialDeepLinkingActivity" android:exported="true">
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="getsocial" android:host="YOUR_APP_ID" />
    </intent-filter>
</activity>

This is done because Unity main activity handles Activity.onNewIntent callback internally, so when the app is launched from browser link we need to intercept the correct intent and forward it GetSocial.

GetSocial.setOnReferralDataReceivedListener(function(referralData){
   //Process referral Data
});

This callback will be called after the succesful GetSocial SDK initialization and if we match the install or open with a previous click on a Smart Invite link.

Deep Linking

When a user clicks on a smart invite link, we will check if the user has the app installed on the device.

If the link is opened on an unsupported device or on computer, we will show a landing page for your app with the links to all available stores.

iOS Specific

Using Url Schemes for iOS 8

Deep linking on iOS 8 works through Url Schemes. You can register an Url Scheme like getsocial:// in your app and the OS will open your app when the user clicks on a link, or is redirected to a url that starts with that Url Scheme.

To register an Url Scheme in your app, open the .plist file for your project and create an array key called URL types with a single array sub-item called URL Schemes.

Add a single string item inside with this content getsocial-[YOUR_APP_ID]. You can find the [YOUR_APP_ID] in the App Information section of the GetSocial Dashboard.

The Smart Invites link will use it to open your app if it is already installed.

Apple introduced Universal Links on iOS 9 to remove some of the pain points of Url Schemes. Universal Links allows you to use regular Urls instead of the Url Schemes, and takes care automatically of the fallback if your app is not installed on the device.

Although Universal Links sound great, their configuration can be a bit painful.

Let us help you through the setup process.

Enabling Associated Domains for your App Identifier

The first step starts on developer.apple.com.

Open Identifiers > App IDs from the left menu and choose your app from the list.

Click on Edit and search for the Associated Domains section and enable the service.

Enabling Associated Domains for your App Identifier

Scroll down and click Done.

After saving, you will need to re-generate and re-download the provisioning profiles associated with this App Identifier, otherwise, it won’t work, trust us, it won’t work.

Important

If you were using a Wildcard App Identifier (i.e. im.getsocial.*), you will need to create a new specific App Identifier and new Provisioning Profiles for your app or the Universal links won’t work.

Enabling Associated Domains in your project

Once Associated Domains is enabled on developer.apple.com, open your Xcode project and enable the com.apple.developer.associated-domains entitlements for your app and include a list of all the domains that your app needs to handle as Universal Links.

To do this in Xcode, open the Associated Domains section in the Capabilities tab, enable the service and add applinks:sm.getsocial.im as domain.

You will also need to add applinks:sm-alt.getsocial.im as domain. This domain works as a fallback when user clicks on the link on Twitter/FB Messenger/Line/Kik/KakaoTalk and is invisible for the user.

These providers make us of in app browsers and require a special approach.

Enabling Associated Domains in your project

If you want to use a custom domain for Smart Invites, you will need to add your domain here like applinks:invites.yourdomain.com.

Enabling Associated Domains in your project

If there is any configuration problem at this stage, Xcode will let you know.

The first validation refers to the entitlements file and there shouldn’t be any errors here since Xcode generates the file automatically for you.

The second validation refers to the app identifiers. The most common error is not having correctly enabled Associated Domains for this specific App Identifier or didn’t update the provisioning profile with the new service (as we told you before :P).

Important

Sometimes Xcode has trouble including the new entitlement file in the right build target. Just make sure it is added correctly before spending hours trying to understand why it doesn’t work.

Unity

To simplify setup process in Unity uncomment the line AddAppEntitlements(projectPath, project, target); in DemoAppIOSPostprocess.cs. This will automatically add entitlements file to test app XCode project, enable Associated Domains in Capabilities and add applinks:sm.getsocial.im as a domain. (The reason it is not enabled by default is to be able to run the app for those who didn’t enable associated domains on developer.apple.com)

Finally, you need to make sure that your app is correctly set up on the GetSocial Dashboard.

For finishing the configuration, you will need to first get the TeamId (shown as Prefix) and BundleId (shown as Id) of your App from the developer.apple.com

Enabling Universal Links on GetSocial

These two values are needed to generate the proper apple-app-site-association file and save you from all the HTTPS/SSL certificates work that is required for Universal Links to work.

In the GetSocial Dashboard select your app and go to Invites > Custom domain.
Just enter TeamId and BundleId of your App and save.

Enabling Universal Links on GetSocial

Ufff, we are done! Wait, Wait, one more thing, before testing it…

Uninstall the app and install it again after all this setup to make sure all changes are being applied.

For this to work properly, you will need to add the following lines in your Manifest file inside the main activity definition.

<intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="getsocial" android:host="YOUR_APP_ID" />
</intent-filter>

Android Specific
In order for deep linking to work correctly and to be able to receive the referral data correctly you have to declare the following activity in your app manifest:

<activity android:name="im.getsocial.sdk.core.unity.GetSocialDeepLinkingActivity" android:exported="true">
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="getsocial" android:host="YOUR_APP_ID" />
    </intent-filter>
</activity>

Info

You can find the [YOUR_APP_ID] in the App Information section of the GetSocial Dashboard.

Using custom domains

Using your own custom domain (i.e. yourcustomdomain.com) for smart invites is also possible, but requires some extra steps.

You will need to first add a CNAME record pointing to custom-invites.getsocial.im in the DNS of the domain/subdomain you want to start using and after that specify it in the GetSocial Dashboard inside Smart Invites > Custom Domain.

Take in mind, that it might take up to 48 hours for this change to propagate.

We will check that the DNS configuration of the specified domain/subdomain is valid.

The parameter Suffix in Smart Invites > Custom Domain section is mandatory for iOS 9 or higher. Don’t modify this parameter if it isn’t necessary, because you will invalidate all the previously generated smart invite links

Important

The domain you choose will only work for smart invites, you can’t reuse a domain/subdomain that is being used for another purpose.

We recommend to use a subdomain, because some DNS providers (i.e. AWS Route53) don’t allow you to add a CNAME records to a root domain.

iOS Specific

If you want to support Universal Links on iOS 9 devices, you will also need to upload a SSL certificate and private key to the GetSocial Dashboard.

  1. Please create a X.509 .pem with the Entire SSL Certificate Trust Chain
  2. Download your Intermediate (DigiCertCA.crt), Root (TrustedRoot.crt) and Primary Certificates (your_domain_name.crt).
  3. Open a text editor (such as wordpad) and paste the entire body of each certificate in the following order:
The Primary Certificate - your_domain_name.crt
The Intermediate Certificate - DigiCertCA.crt
The Root Certificate - TrustedRoot.crt

Make sure to include the beginning and end tags on each certificate.

The result should look like this:

-----BEGIN CERTIFICATE-----
(Your Primary SSL certificate: your_domain_name.crt)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(Your Intermediate certificate: DigiCertCA.crt)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(Your Root certificate: TrustedRoot.crt)
-----END CERTIFICATE-----

Finally paste it as the Certificate and enter the Private key as well.

Please contact us if you need any help setting this up.

Chat UI

To start using GetSocial Chat you have to add libraries to the project. Check Adding GetSocial to your app section for more information.

Also ui is fully customizable, so you can blend it into your application or game, see UI Customization guide for more details.

List of rooms

Invite Friends

This view displays the list of recent conversations in private rooms and allow users to start new conversations with their friends:

[[[GetSocialChat sharedInstance] createChatListView] show];
GetSocialChat.sharedInstance().createChatListView().show()
GetSocialChat.getInstance().createChatListView().show();
GetSocialChat.Instance.CreateChatListView().Show();
GetSocialChat.getInstance().createChatListView().show();

Invite Friends

Invite Friends

The GetSocial SDK UI for Chat has embedded entry points to invite new friends using Smart Invites. If you want to customize or override this behavior you can register this handler.

[[GetSocial sharedInstance] setOnInviteButtonClickHandler:^BOOL{
    // Custom code to handle the invite button click
    // return YES to indicate that you'll handle event, or NO if SDK should handle it
    return YES;
}];
GetSocial.sharedInstance().setOnInviteButtonClickHandler { () -> Bool in
    // custom code to handle the invite button click
    // return 'true' to indicate that you'll handle event, or 'false' if SDK should handle it
    return true
}
getSocial.setOnInviteButtonClickHandler(new GetSocial.OnInviteButtonClickHandler()
{
    @Override
    public boolean OnInviteButtonClick()
    {
        // Custom code to handle the invite button click
        // return true to indicate that you'll handle event, or false if SDK should handle it
        return true;
    }
});
getSocial.SetOnInviteButtonClickListener(() => {
    // Custom code to handle the invite button click
    // return true to indicate that you'll handle event, or false if SDK should handle it
    return true;
});
GetSocial.setOnInviteButtonClickListener(function(isManualProcessed, onResult) {
        // Custom code to handle the invite button click
});

Private Chat rooms

Invite Friends

You can also directly open a private chat conversation from user’s avatar within the app using their User Id on supported Social Providers like kGetSocialProviderFacebookUserIdentity.PROVIDER_FACEBOOKUserIdentity.ProviderFacebook"facebook" or kGetSocialProviderGooglePlusUserIdentity.PROVIDER_GOOGLEPLUSUserIdentity.ProviderGooglePlus"googleplus".

[[[GetSocialChat sharedInstance] createChatViewForUserId:@"0123456789"
    onProvider:kGetSocialProviderFacebook] show];
GetSocialChat.sharedInstance().createChatViewForUserId("0123456789",
    onProvider: kGetSocialProviderFacebook).show()
GetSocialChat.getInstance().createChatViewForUserIdOnProvider("0123456789", UserIdentity.PROVIDER_FACEBOOK).show();
GetSocialChat.Instance.CreateChatViewForUserIdOnProvider(FB.UserId, UserIdentity.ProviderFacebook).Show();

Tip

Use ENABLE_GETSOCIAL_CHAT preprocessor directive is added to “Scripting Define Symbols”. You can use the directive to strip parts of your code related to chat functionality when the module is disabled.

var userId = "0123456789";
var providerId = "facebook";
GetSocialChat.getInstance().createChatViewForUserIdOnProvider(userId,providerId).show();

Public Chat rooms

Public Chat rooms are magical constructs where kind spirits from your community come together to chat about life, the universe, and everything. As a developer, you are in full control of which users can participate in these rooms, and the number of rooms is unlimited.

GetSocialChatViewBuilder *viewBuilder = [[GetSocialChat sharedInstance]
    createChatViewForRoomName:@"roomname"];

[viewBuilder setTitle:@"Custom title"];
[viewBuilder show];
var viewBuilder = GetSocialChat.sharedInstance().createChatViewForRoomName("roomname")
viewBuilder.title = "Custom title"
viewBuilder.show()
GetSocialChat.getInstance().createChatViewForRoomName("roomname").setTitle("Custom title").show();
GetSocialChat.Instance.CreateChatViewForRoomName("roomName").SetTitle("Custom title").Show();
GetSocialChat.getInstance().createChatViewForRoomName("roomName").setTitle("Custom Title").show();

Chat API

To start using GetSocial Chat you have to add libraries to the project. Check Adding GetSocial to your app section for more information.

GetSocial Chat API lets you access all chat related data to build your own UI or perform a deep integration into your app or game.

Working with rooms

The Chat API provides two types of chat rooms:
- Private room - this is a room that has only two participants and no one else can enter the room. It is suitable when two users have one-on-one conversation.
- Public room - this is a room that everyone can join. Once you subscribe to this room, you will start receiving messages

Private rooms

To get a list with all private rooms in which current user is a participant you need to call:

[[GetSocialChat sharedInstance] privateRoomsWithSuccess:^(NSArray<GetSocialPrivateChatRoom *> *rooms) {
     //rooms can be empty if there are no rooms in which current user is participant
} failure:^(NSError *error) {
    //code
}
GetSocialChat.sharedInstance().privateRoomsWithSuccess({ (privateChatRooms: [GetSocialPrivateChatRoom]!) in
     //rooms can be empty if there are no rooms in which current user is participant
}) { (error: NSError!) in
    //code
}

GetSocialChat.getInstance().getPrivateRooms(new OperationCallback<List<PrivateChatRoom>>()
{
    @Override
    public void onSuccess(List<PrivateChatRoom> chatRooms)
    {
        //data can be empty if there are no rooms in which current user is participant
    }

    @Override
    public void onFailure(Exception exception)
    {
        //code here
    }
});
GetSocialChat.Instance.GetAllPrivateRooms(
    rooms =>
    {
        // rooms can be empty if there are no rooms in which current user is participant
    },
    error =>
    {
        // code
    });
Coming soon...

You can also get a room with a specific user. Please note if the room does not exist it will be created. You can do this by calling:

GetSocialUser *user = ....

[[GetSocialChat sharedInstance] privateRoomWithUser:user success:^(GetSocialPrivateChatRoom *privateRoom) {
    //code
} failure:^(NSError *error) {
    //code
}];
let user: GetSocialUser = ...
GetSocialChat.sharedInstance().privateRoomWithUser(user, success: { (privateChatRoom: GetSocialPrivateChatRoom!) in
    //code
}) { (error: NSError!) in
    //code
}
User user = ...

GetSocialChat.getInstance().getPrivateRoom(user, new OperationCallback<PrivateChatRoom>()
{
    @Override
    public void onSuccess(PrivateChatRoom data)
    {
        //code
    }

    @Override
    public void onFailure(Exception exception)
    {
        //code
    }
});
User user = GetUser();
GetSocialChat.Instance.GetPrivateRoom(user,
    room =>
    {
        // code
    },
    error =>
    {
        // code
    });
Coming soon...

Public rooms

A list of a public rooms can not be requested. You can get a global room only by its name. Please note that if the room does not exist it will be created.

NSString* roomName = @"ChatRoom";
[[GetSocialChat sharedInstance] publicRoomWithName:roomName success:^(GetSocialPublicChatRoom *room) {
    //code
} failure:^(NSError *error) {
    //code
}];
let roomName = "ChatRoom"
GetSocialChat.sharedInstance().publicRoomWithName(roomName, success: { (publicChatRoom : GetSocialPublicChatRoom!) in
    //code
}) { (error : NSError!) in
    //code
}

GetSocialChat.getInstance().getPublicRoom(roomName, new OperationCallback<PublicChatRoom>()
{
    @Override
    public void onSuccess(PublicChatRoom room)
    {
        //code
    }

     @Override
    public void onFailure(Exception exception)
    {
        //code
    }
});
GetSocialChat.Instance.GetPublicRoom("ChatRoom",
    room =>
    {
        // code
    },
    error =>
    {
        // code
    });
Coming soon...

Send messages

When you send a message you must first define the content of the message. You can see this from the code below:

GetSocialPrivateChatRoom *chatRoom = ...

//this will create a text message content
GetSocialChatMessageContent *content = [GetSocialChatMessageContent contentWithText:@”Hello”];

//here you send the content, but you are getting back the full message, if the content is sent successfully
[privateChatRoom sendMessage:content success:^() {
    // message was sent
} failure:^(NSError *error) {
    // failed to send message
}];
let privateRoom: GetSocialPrivateChatRoom
let content = GetSocialChatMessageContent(text: "Hello")

privateRoom.sendMessage(content, success: {
    // message was sent
}) { (error: NSError!) in
    // failed to send message
}
PrivateChatRoom chatRoom = ...

//this will create a text message content
ChatMessageContent textContent = ChatMessageContent.createWithText(“Hello”);

//here you send the content, but you are getting back the full message if the content is sent successfully
chatRoom.sendMessage(textContext, new OperationCallback<ChatMessage>()
{
    @Override
    public void onSuccess()
    {
        // message was sent
    }

    @Override
    public void onFailure(Exception exception)
    {
        // failed to send message
    }
});
IPrivateChatRoom room = GetPrivateRoom();
var content = ChatMessageContent.CreateWithText("Hello");

room.SendMessage(content,
    () =>
    {
        // message was sent
    },
    error =>
    {
        // sending message failed
    });
Coming soon...

Receive Messages

Chat API gives you the opportunity to listen for messages in private rooms separately from those in public rooms.

First thing you need to do is to create a room listener:


self.publicRoomMessageHandler = ^(GetSocialPublicChatRoom *room, GetSocialChatMessage *message) {
    // handle message
};

self.privateRoomMessageHandler = ^(GetSocialPrivateChatRoom *room, GetSocialChatMessage *message) {
    // handle message
};

let publicRoomMessageHandler = { (publicChatRoom: GetSocialPublicChatRoom!, message: GetSocialChatMessage!) in
    // handle message
}

let privateRoomMessageHandler = { (privateChatRoom: GetSocialPrivateChatRoom!, message: GetSocialChatMessage!) in
    // handle message
}

GetSocialChat.RoomMessageListener roomMessageListener = new GetSocialChat.RoomMessageListener()
{
  @Override
  public void onPublicRoomMessage(PublicChatRoom chatRoom, ChatMessage chatMessage)
  {
     //public rooms' messages
  }

  @Override
  public void onPrivateRoomMessage(PrivateChatRoom chatRoom, ChatMessage chatMessage)
  {
     //private rooms' messages
  }
}

private class MessagesListener : IChatMessageListener
{
    public void OnPublicRoomMessage(IPublicChatRoom publicRoom, ChatMessage message)
    {
        // public room message received
    }

    public void OnPrivateRoomMessage(IPrivateChatRoom privateRoom, ChatMessage message)
    {
        // private room message received
    }
}

...

var messagesListener = new MessagesListener();
Coming soon...

You can listen for messages in private and public rooms by registering your listener:

[[GetSocialChat sharedInstance] addHandlerForPublicRoomMessage:self.publicRoomMessageHandler privateRoomMessage:self.privateRoomMessageHandler];

GetSocialChat.sharedInstance().addHandlerForPublicRoomMessage(publicRoomMessageHandler, privateRoomMessage: privateRoomMessageHandler)

GetSocialChat.getInstance().addRoomMessageListener(roomMessageListener);
GetSocialChat.Instance.AddMessageListener(messagesListener);
Coming soon...

Please note that there is a difference between public and private rooms. To listen for messages in private rooms all you need to do is to set up your listener. After that you will be able to listen for messages in all private rooms that you are participant.

On the other hand to listen for messages for public rooms you first need to make sure that you are subscribed for the room.

You can subscribe for public room by calling:

GetSocialPublicChatRoom *publicRoom = ...

[publicRoom subscribeWithSuccess:^{
    //code
} failure:^(NSError *error) {
    //code
}];
let publicChatRoom : GetSocialPublicChatRoom = ...
publicChatRoom.subscribeWithSuccess({
    // code
}) { (error : NSError!) in
    // code
}
PublicChatRoom publicChatRoom = ...

publicChatRoom.subscribe(new OperationVoidCallback()
{
    @Override
    public void onSuccess()
    {
        //code
    }

    @Override
    public void onFailure(Exception exception)
    {
        //code
    }
});
var publicRoom = GetPublicRoom();
publicRoom.Subscribe(
    () =>
    {
        // successfully subscribed
    },
    error =>
    {
        // failed to subscribe
    });
Coming soon...

Removing listeners:

[[GetSocialChat sharedInstance] removeHandlerForPublicRoomMessage:self.publicRoomMessageHandler
    privateRoomMessage:self.privateRoomMessageHandler];
GetSocialChat.sharedInstance().removeHandlerForPublicRoomMessage(publicRoomMessageHandler, privateRoomMessage: privateRoomMessageHandler)
GetSocialChat.getInstance().removeRoomMessageListener(roomMessageListener);
GetSocialChat.Instance.RemoveMessageListener(messagesListener);
Coming soon...

Important

To avoid memory leaks and app misbehaviour do not forget to remove your listeners when you don’t need them anymore.

Typing Status

Whenever a user starts typing there is an option to set a “typing status” to the participants in the room. Other users will receive that status and UI can for example show a message that says “User X is typing”.

Please note that the same status can’t be set more frequently than specific interval. For example if you call setTypingStatus twice with the same status the receiver is going to get only the first call if the interval between the the two calls is less than the one defined (Check the reference docs of setTypingStatus to learn more about allowed intervals).
To set a typing status of the current user you have to call:

GetSocialTypingStatus status = GetSocialTypingStatusTyping;

[self.currentRoom setTypingStatus:status success:^{
    //code
} failure:^(NSError *error) {
    //code
}];
let status = GetSocialTypingStatus.Typing
chatRoom.setTypingStatus(status, success: {
    // code
}) { (error : NSError!) in
    // code
}
TypingStatus ts = TypingStatus.TYPING;

chatRoom.setTypingStatus(ts, new OperationVoidCallback()
{
  @Override
  public void onSuccess()
  {
    //code
  }

  @Override
  public void onFailure(Exception exception)
  {
    //code
  }
});
var room = GetPrivateRoom();
room.SetTypingStatus(TypingStatus.Typing,
    () =>
    {
        // success
    },
    error =>
    {
        // failure
    });
Coming soon...

GetSocial guarantees NOT_TYPING status is always delivered, so if for some reason the sender doesn’t set NOT_TYPING(for example drop of the connection) the receiver will get NOT_TYPING in specific interval after the last TYPING. (Check the reference docs of setTypingStatus to learn more about allowed intervals)
To receive a typing status you need to create the following listener:

self.publicRoomTypingStatusHandler = ^(GetSocialPublicChatRoom *room, GetSocialUser *user, GetSocialTypingStatus typingStatus) {
    // handle typing status
};

self.privateRoomTypingStatusHandler = ^(GetSocialPrivateChatRoom *room, GetSocialUser *user, GetSocialTypingStatus typingStatus) {
    // handle typing status
};

let publicRoomTypingStatusHandler = { (publicChatRoom: GetSocialPublicChatRoom!, user: GetSocialUser! typingStatus: GetSocialTypingStatus) in
    // handle typing status
}

let privateRoomTypingStatusHandler = { (privateChatRoom: GetSocialPrivateChatRoom!, user: GetSocialUser! typingStatus: GetSocialTypingStatus!) in
    // handle typing status
}

GetSocialChat.RoomTypingStatusListener roomTypingStatusListener = new GetSocialChat.RoomTypingStatusListener()
{
  @Override
  public void onPublicRoomTypingStatus(PublicChatRoom chatRoom, User user, TypingStatus typingStatus)
  {
    //code
  }

  @Override
  public void onPrivateRoomTypingStatus(PrivateChatRoom chatRoom, User user, TypingStatus typingStatus)
  {
    //code
  }
}
private class TypingStatusListener : ITypingStatusLestener
{
    public void OnPublicRoomTypingStatusReceived(IPublicChatRoom room, User user, TypingStatus typingStatus)
    {
        // code
    }

    public void OnPrivateRoomTypingStatusReceived(IPrivateChatRoom room, User user, TypingStatus typingStatus)
    {
        // code
    }
}

...

var typingStatusListener = new TypingStatusListener();
Coming soon...

After you have the listener you can register it by:

[[GetSocialChat sharedInstance] addHandlerForPublicRoomTypingStatus:self.publicRoomTypingStatusHandler privateRoomTypingStatus: self.privateRoomTypingStatusHandler];
}];
GetSocialChat.sharedInstance().addHandlerForPublicRoomTypingStatus(publicRoomTypingStatusHandler, privateRoomTypingStatus: privateRoomTypingStatusHandler)
GetSocialChat.getInstance().addRoomTypingStatusListener(roomTypingStatusListener)
GetSocialChat.Instance.AddTypingStatusListener(typingStatusListener);
Coming soon...

Removing typing status listeners:

[[GetSocialChat sharedInstance] removeHandlerForPublicRoomTypingStatus:self.publicRoomTypingStatusHandler privateRoomTypingStatus:self.privateRoomTypingStatusHandler];
GetSocialChat.sharedInstance().removeHandlerForPublicRoomTypingStatus(publicRoomTypingStatusHandler, privateRoomTypingStatus: privateRoomTypingStatusHandler)
GetSocialChat.getInstance().removeRoomTypingStatusListener(roomTypingStatusListener);
GetSocialChat.Instance.RemoveTypingStatusListener(typingStatusListener);
Coming soon...

Important

To avoid memory leaks and app misbehaviour do not forget to remove your listeners when you don’t need them anymore.

Chat history

All the messages for a particular room can be requested page by page. In the example below you are requesting 5 messages older than the chatMessage.

GetSocialChatMessage chatMessage = ...
NSInteger limit = 5;

GetSocialPrivateRoom chatRoom = ...
[chatRoom messagesBeforeChatMessage:chatMessage //pass nil if you want to start from the last message
            limit:limit
            success:^(NSArray<GetSocialChatMessage *> *messages) {
                //code
            }
            failure:^(NSError *error) {
                //code
            }];
let chatMessage : GetSocialChatMessage = ... //nil if you want to start from the last message
Int limit = 5
chatRoom.messagesBeforeChatMessage(chatMessage, limit: limit, success: { (messages : [GetSocialChatMessage]!) in
    // code
}) { (error : NSError!) in
    // code
}
ChatMessage chatMessage = ...
int limit = 5;

PrivateChatRoom chatRoom = ...
chatRoom.getMessagesBeforeChatMessage(chatMessage, //pass null if you want to start from the last message
                    limit, new OperationCallback<List<UserChatMessage>>()
                    {
                        @Override
                        public void onSuccess(List<ChatMessage> data)
                        {
                            //code
                        }

                        @Override
                        public void onFailure(Exception exception)
                        {
                            //code
                        }
                    });
ChatMessage lastChatMessage = GetChatMessage();
const int limit = 5;

var room = GetPrivateRoom();
room.GetMessages(lastChatMessage, limit,
    messages =>
    {
        // successfully got messages
    },
    error =>
    {
        // failed to get messages
    });
Coming soon...

Unread rooms count

Unread rooms are rooms that have one or more messages that haven’t been read yet.
As soon as you receive a message in a room, Chat API marks the room as unread. After that developer decides when to mark the room as read. We recommend to mark room as read when the user opens the unread room and reads the messages.

To mark the room as unread you have to call:

GetSocialPrivateChatRoom chatRoom = ...

[chatRoom markAsReadWithSuccess:^{
    //code
} failure:^(NSError *error) {
    //code
}];
let privateChatRoom : GetSocialPrivateChatRoom = ...
privateChatRoom.markAsReadWithSuccess({
    // code
}) { (error: NSError!) in
    // code
}
PrivateChatRoom chatRoom = ...

chatRoom.markAsRead(new OperationVoidCallback()
{
    @Override
    public void onSuccess()
    {
        //code
    }

    @Override
    public void onFailure(Exception exception)
    {
        //code
    }
});
var room = GetPublicRoom();
room.MarkAsRead(
    () =>
    {
        // successfully marked as read
    },
    error =>
    {
        // failed to mark as read
    });
Coming soon...

Chat API also gives you the possibility to listen for a change in the unread rooms counter.

You need to declare your listener like:

self.onUnreadPublicRoomsCountChangeHandler = ^(NSInteger unreadPublicRoomsCount) {
    // code
};

self.onUnreadPrivateRoomsCountChangeHandler = ^(NSInteger unreadPrivateRoomsCount) {
    // code
};

let unreadPublicRoomCountChangeHandler = { (unreadPublicRooms: Int) in
    // code
}
let unreadPrivateRoomCountChangeHandler = { (unreadPrivateRooms: Int) in
    // code
}

GetSocialChat.OnUnreadRoomsCountChangedListener unreadRoomsCountChangeListener = new GetSocialChat.OnUnreadRoomsCountChangedListener()
{
  @Override
  public void onUnreadPublicRoomsCountChanged(int unreadPublicRoomsCount)
  {
     //code
  }

  @Override
  public void onUnreadPrivateRoomsCountChanged(int unreadPrivateRoomsCount)
  {
     //code
  }
});

private class UnreadCountChangedListener : IUnreadRoomCountChangedListener
{
    public void OnUnreadPublicRoomsCountChanged(int count)
    {
        // code
    }

    public void OnUnreadPrivateRoomsCountChanged(int count)
    {
        // code
    }
}

...

var unreadCountChangedListener = new UnreadCountChangedListener();
Coming soon...

You can register to listening for change in the count by calling:

[[GetSocialChat sharedInstance] addOnUnreadRoomsCountChangeHandler:self.onUnreadPublicRoomsCountChangeHandler
                                onUnreadPrivateRoomsCountChangeHandler:self.onUnreadPrivateRoomsCountChangeHandler];
GetSocialChat.sharedInstance().addOnUnreadRoomsCountChangeHandler(unreadPublicRoomCountChangeHandler, onUnreadPrivateRoomsCountChangeHandler: unreadPrivateRoomCountChangeHandler)

GetSocialChat.getInstance().addOnUnreadRoomsCountChangedListener(unreadRoomsCountChangeListener);
GetSocialChat.Instance.AddOnUnreadRoomCountChangedListener(unreadCountChangedListener);
Coming soon...

You also can check the current amount of unread rooms by calling:

//private rooms
NSInteger count = [GetSocialChat sharedInstance].unreadPrivateRoomsCount;

//public rooms
NSInteger count = [GetSocialChat sharedInstance].unreadPublicRoomsCount
// private rooms
Int count = GetSocialChat.sharedInstance().unreadPrivateRoomsCount()

// public rooms
Int count = GetSocialChat.sharedInstance().unreadPublicRoomsCount()
//private rooms
int count = GetSocialChat.getInstance().getUnreadPrivateRoomsCount();

//public rooms
int count = GetSocialChat.getInstance().getUnreadPublicRoomsCount();
//private rooms
int privateCount = GetSocialChat.Instance.UnreadPrivateRoomsCount;

//public rooms
int publicCount = GetSocialChat.Instance.UnreadPublicRoomsCount;
Coming soon...

Removing unread rooms count change listeners:

[[GetSocialChat sharedInstance] removeOnUnreadRoomsCountChangeHandler:onUnreadPublicRoomsCountChangeHandler onUnreadPrivateRoomsCountChangeHandler:onUnreadPrivateRoomsCountChangeHandler];
GetSocialChat.sharedInstance().removeOnUnreadRoomsCountChangeHandler(unreadPrivateRoomCountChangeHandler, onUnreadPrivateRoomsCountChangeHandler: unreadPrivateRoomCountChangeHandler)

GetSocialChat.getInstance().removeOnUnreadRoomsCountChangedListener(onUnreadRoomsCountChangedListener);

GetSocialChat.Instance.RemoveOnUnreadRoomCountChangedListener(unreadCountChangedListener);
Coming soon...

Important

To avoid problems do not forget to remove your listeners when you don’t need them anymore.

Notification Center

Activity feed and Chat features are incomplete without having the In-app Notification Center that provides in-app notifications to users when someone likes or comments on their activities or when they receive chat messages.

[[[GetSocial sharedInstance] createNotificationsView] show];
GetSocial.sharedInstance().createNotificationsView().show()
getSocial.createNotificationsView().show();
getSocial.CreateNotificationsView().Show();
var notificationsView = new GetSocial.NotificationsViewBuilder();
notificationsView.show();

It is highly recommended that you link this to a UI element with a notifications count badge. The SDK provides an ability to get a count of the unread chats and activity notifications.

[[GetSocial sharedInstance] setOnNotificationsChangeHandler:^(NSInteger unreadNotificationsCount) {
    //code to handle changes on Notifications/Conversations counts
}];

[[GetSocialChat sharedInstance] setOnChatNotificationsChangeHandler:^(NSInteger) {
    //code to handle changes on Chat messages counts
}];
GetSocial.sharedInstance().setOnNotificationsChangeHandler { (unreadNotificationsCount : Int) -> Void in
    // code to handle changes on Notifications/Conversations counts
}

GetSocialChat.sharedInstance().setOnChatNotificationsChangeHandler { (unreadMessagesCount : Int) -> Void in
    // code to handle changes on Chat messages count
}
UnreadNotificationsCountMonitor.getInstance().addListener(new OnUnreadNotificationsCountChangedListener()
{
    @Override
    public void onUnreadNotificationsCountChanged(int unreadNotificationsCount)
    {
           // handle change of unread notifications count
    }
});

UnreadConversationsCountMonitor.getInstance().addListener(new OnUnreadConversationsCountChangedListener()
{
    @Override
    public void onUnreadConversationsCountChanged(int unreadConversationsCount)
    {
           // handle change of unread conversations count
    }
});
getSocial.SetOnUnreadNotificationsCountChangeListener((unreadNotifications) => {
    // code to handle changes on unread Notifications counts
});
getSocialChat.SetOnUnreadConversationsCountChangeListener((unreadConversations) => {
    // code to handle changes on unread Conversations counts
});

GetSocial.getInstance().setOnUnreadNotificationsCountChangeListener(function(numOfUnreadNotifications) {
    // code to handle changes on unread Notifications counts
});

GetSocialChat.getInstance().setOnUnreadConversationsCountChangeListener(function(numOfUnreadConversations) {
    // code to handle changes on unread Conversations counts
});

Important

In order to receive activity notification count updates you have to setup push notifications for the respective platform correctly.

Social Graph

GetSocial social graph feature is very similar to Twitter, user has the list of users who are following him (followers) and the list of users that he is following. GetSocial provide API to build, query and display connections in the social graph.

Build the Social Graph

Via adding user identity

When the user adds Facebook or Google+ identity all his friends that are also playing the current game will be automatically followed.

Via Smart Invites

When the user invites another user through Smart invites and the second user installs the app than both users will follow each other.

Via public API

Current user can also add another user to his following list by follow him using the GetSocial public API

GetSocialCurrentUser *currentUser = [GetSocial sharedInstance].currentUser;
[currentUser followUser:user success:^{
  //success following user
} failure:^(NSError *error) {
  //following user failed
}];
let currentUser = GetSocial.sharedInstance().currentUser
currentUser.followUser(user, success: {
  // success following user
}) { (error: NSError!) in
  // following user failed
}
CurrentUser currentUser = GetSocial.getInstance().getCurrentUser();                
currentUser.followUser(user, new OperationVoidCallback()
{
  @Override
  public void onSuccess()
  {
    //success following user
  }

  @Override
  public void onFailure(Exception exception)
  {
    //following user failed
  }
});
GetSocial.Instance.CurrentUser.FollowUser(user,
    () =>
    {
        // success following user
    },
    error =>
    {
        // following user failed
    });

Coming soon…

You can also follow user using provider and userId

NSString *facebookUserId = @"123456789";
GetSocialCurrentUser *currentUser = [GetSocial sharedInstance].currentUser;
[currentUser followUserWithProvider:kGetSocialProviderFacebook userId:facebookUserId success:^{
  //success following user
} failure:^(NSError *error) {
  //following user failed
}];
let currentUser = GetSocial.sharedInstance().currentUser
let facebookUserId = "123456789"
currentUser.followUserWithProvider(kGetSocialProviderFacebook, userId: facebookUserId, success: {
  // success following user
}) { (error: NSError!) in
  // following user failed
}
String facebookUserId = "123456789";
CurrentUser currentUser = GetSocial.getInstance().getCurrentUser();
currentUser.followUser(UserIdentity.PROVIDER_FACEBOOK, "123456789", new OperationVoidCallback()
{
  @Override
  public void onSuccess()
  {
    //success unfollow user
  }

  @Override
  public void onFailure(Exception exception)
  {
    //failed to unfollow user
  }
});
string facebookUserId = "1234567890";
GetSocial.Instance.CurrentUser.FollowUser(UserIdentity.ProviderFacebook, facebookUserId,
    () =>
    {
        // success following user
    },
    error =>
    {
        // following user failed
    });

Coming soon…

At any time current user can unfollow any of the users in his following list using

GetSocialCurrentUser *currentUser = [GetSocial sharedInstance].currentUser;
[currentUser unfollowUser:user success:^{
  //success unfollowing user
} failure:^(NSError *error) {
  //unfollowing user failed
}];
let currentUser = GetSocial.sharedInstance().currentUser
currentUser.unfollowUser(user, success: {
  // success unfollowing user
}) { (error: NSError!) in
  // unfollowing user failed
}
CurrentUser currentUser = GetSocial.getInstance().getCurrentUser();
currentUser.unfollowUser(user, new OperationVoidCallback()
{
  @Override
  public void onSuccess()
  {   
    //success unfollowing user
  }

  @Override
  public void onFailure(Exception exception)
  {
    //unfollowing user failed
  }
});
GetSocial.Instance.CurrentUser.UnfollowUser(user,
    () =>
    {
        // success unfollowing user
    },
    error =>
    {
        // unfollowing user failed
    });

Coming soon…

You can also unfollow user using provider and userId

NSString *facebookUserId = @"123456789";
GetSocialCurrentUser *currentUser = [GetSocial sharedInstance].currentUser;
[currentUser unfollowUserWithProvider:kGetSocialProviderFacebook userId:facebookUserId success:^{
  //success unfollowing user
} failure:^(NSError *error) {
  //unfollowing user failed
}];
let facebookUserId = "123456789"
let currentUser = GetSocial.sharedInstance().currentUser
currentUser.unfollowUserWithProvider(kGetSocialProviderFacebook, userId:facebookUserId, success: {
  // success unfollowing user
}) { (error: NSError!) in
  // unfollowing user failed
}
String facebookUserId = "123456789";
CurrentUser currentUser = GetSocial.getInstance().getCurrentUser();
currentUser.unfollowUser(UserIdentity.PROVIDER_FACEBOOK, facebookUserId, new OperationVoidCallback()
{
  @Override
  public void onSuccess()
  {
    //success unfollow user
  }

  @Override
  public void onFailure(Exception exception)
  {
    //failed to unfollow user
  }
});
string facebookUserId = "1234567890";
GetSocial.Instance.CurrentUser.UnfollowUser(UserIdentity.ProviderFacebook, facebookUserId,
    () =>
    {
        // success unfollowing user
    },
    error =>
    {
        // unfollowing user failed
    });

Coming soon…

Query the Social Graph

You can use the GetSocial public API to list all the users that you follow page by page

NSInteger offset = 0; //the offset index. In that case get first record
NSinteger count = 10; //records to be returned. Less can be returned if total is less
GetSocialCurrentUser *currentUser = [GetSocial sharedInstance].currentUser;
[currentUser followingWithOffset:offset
        count:count
        success:^(NSArray<GetSocialUser *> *following) {
          // successfully got the list of following
        }
        failure:^(NSError *error) {
          // retrieving list of following users failed
        }];
let offset = 0 //the offset index. In that case get first record
let count = 10 //records to be returned. Less can be returned if total is less
let currentUser = GetSocial.sharedInstance().currentUser
currentUser.followingWithOffset(offset, count: count, success: { (following: [GetSocialUser]!) in
  // successfully got the list of following
}) { (error: NSError!) in
    // retrieving list of following users failed
}
int offset = 0; //the offset index. In that case get first record
int count = 10; //records to be returned. Less can be returned if total is less
CurrentUser currentUser = GetSocial.getInstance().getCurrentUser();      
currentUser.getFollowing(offset, count, new OperationCallback<List<User>>()
{
  @Override
  public void onSuccess(List<User> following)
  {
    // successfully got the list of following
  }

  @Override
  public void onFailure(Exception exception)
  {
    // retrieving list of following users failed
  }
});
int offset = 0; //the offset index. In that case get first record
int count = 10; //records to be returned. Less can be returned if total is less
GetSocial.Instance.CurrentUser.GetFollowing(offset, count,
    users =>
    {
        // successfully got the list of following
    },
    error =>
    {
        // retrieving list of following users failed
    });

Coming soon…

You can also list all the followers page by page

NSInteger offset = 0; //the offset index. In that case get first record
NSInteger count = 10; //records to be returned. Less can be returned if total is less
GetSocialCurrentUser *currentUser = [GetSocial sharedInstance].currentUser;
[currentUser followersWithOffset:offset
        count:count
        success:^(NSArray<GetSocialUser *> *followers) {
          // process list followers
        }
        failure:^(NSError *error) {
            // operation failed
        }];
let offset = 0 //the offset index. In that case get first record
let count = 10 //records to be returned. Less can be returned if total is less
let currentUser = GetSocial.sharedInstance().currentUser
currentUser.followersWithOffset(offset, count: count, success: { (following: [GetSocialUser]!) in
  // process list followers
}) { (error: NSError!) in
  // operation failed
}
int offset = 0; //the offset index. In that case get first record
int count = 10; //records to be returned. Less can be returned if total is less
CurrentUser currentUser = GetSocial.getInstance().getCurrentUser();      
currentUser.getFollowers(offset, count, new OperationCallback<List<User>>()
{
  @Override
  public void onSuccess(List<User> followers)
  {

  }

  @Override
  public void onFailure(Exception exception)
  {

  }
});
int offset = 0; //the offset index. In that case get first record
int count = 10; //records to be returned. Less can be returned if total is less
GetSocial.Instance.CurrentUser.GetFollowers(offset, count,
    users =>
    {
        // successfully got the list of followers
    },
    error =>
    {
        // retrieving list of followers failed
    });

Coming soon…

Display the Social Graph

You can show a list of users that current user follows using our UI.

Friends List

GetSocialUserListViewBuilder *viewBuilder =
    [[GetSocial sharedInstance] createUserListViewWithType:GetSocialUserListFollowingType dismissHandler:^(GetSocialUser *user, BOOL didCancel) {
        if (!didCancel)
        {
          //user is selected
        }
        else
        {
          //following list is closed
        }
    }];
viewBuilder.title = @"Following";
[viewBuilder show];
let viewBuilder = GetSocial.sharedInstance().createUserListViewWithType(.FollowingType) { (user: GetSocialUser!, didCancel: Bool) in
  if !didCancel {
    // user is selected
  }else{
    // following list is closed
  }
}
viewBuilder.title = "Following"
viewBuilder.show()
GetSocial.getInstance().createUserListView(UserListViewBuilder.UserListType.FOLLOWING,
    new UserListViewBuilder.UserListObserver()
    {
      @Override
      public void onUserSelected(final User user)
      {
        //user is selected
      }

      @Override
      public void onCancel()
      {
        //following list is closed
      }
    }).setTitle("Following").show();
GetSocial.Instance.CreateUserListView(UserListViewBuilder.UserListType.Following,
    user =>
    {
        // user is selected
    },
    () =>
    {
        // following list is closed
    }).SetTitle("Following").Show();

Coming soon…

You can also show a list of all the users that follow the current user(followers) using our UI

GetSocialUserListViewBuilder *viewBuilder =
    [[GetSocial sharedInstance] createUserListViewWithType:GetSocialUserListFollowersType dismissHandler:^(GetSocialUser *user, BOOL didCancel) {
        if (!didCancel)
        {
            //user is selected
        }
        else
        {
            //followers list is closed
        }
    }];
viewBuilder.title = @"Followers";
viewBuilder.showInviteButton = NO;
[viewBuilder show];
let viewBuilder = GetSocial.sharedInstance().createUserListViewWithType(.FollowersType) { (user: GetSocialUser!, didCancel: Bool) in
  if !didCancel {
    // user is selected
  }else{
    // followers list is closed
  }
}
viewBuilder.title = "Followers"
viewBuilder.show()
GetSocial.getInstance().createUserListView(UserListViewBuilder.UserListType.FOLLOWERS,
    new UserListViewBuilder.UserListObserver()
    {
      @Override
      public void onUserSelected(final User user)
      {
        //user is selected
      }

      @Override
      public void onCancel()
      {
        //followers list is closed
      }
    }).setTitle("Followers").setShowInviteButton(false).show();
GetSocial.Instance.CreateUserListView(UserListViewBuilder.UserListType.Followers,
    user =>
    {
        // user is selected
    },
    () =>
    {
        // followers list is closed
    }).SetTitle("Followers").Show();

Coming soon…

Push Notifications

iOS Specific

Before starting, you need to generate the right Push Notification Certificates on Apple Developer Portal and upload them on GetSocial Dashboard. Upload the Development and/or Production Certificate and choose which one to use.

To start sending Push Notifications to the user’s device, GetSocial will ask for permissions to users the first time they log in. We ask for the Alert and Sound permissions.

You do not need to add any code to your app as GetSocial handles everything internally. By default GetSocial will enable your push notifications during init process.
If you want to delay the registration for the push notifications you first need to disable the auto registration.

You can do that by calling

[GetSocial sharedInstance].disableAutoRegistrationForPushNotifications = YES;
GetSocial.sharedInstance().disableAutoRegistrationForPushNotifications = true

In that case your device won’t be registered for push notifications during init process.

If you want you can manually register for push notifications at any time by calling:

[[GetSocial sharedInstance] registerForPushNotifications];
GetSocial.sharedInstance().registerForPushNotifications()

To disable auto registration go to GetSocial -> Edit Settings and turn off the checkbox in iOS Specific Settings section

image alt text

To register for push notifications at any point in time you can call the method provided in Unity API

Example:

NotificationServices.RegisterForNotifications(
    NotificationType.Alert |
    NotificationType.Badge |
    NotificationType.Sound);

Android Specific

To enable Google Cloud Messaging (GCM) for Android, you will need to turn on the Google Cloud Messaging Services from Google’s API Console page.

  1. First select “APIs & auth” from the left-hand navigation and click on “APIs”.
  2. Then find “Google Cloud Messaging for Android” in the list and turn it on by clicking the switch in the “Status” column.
  3. Finally create a Google API key from the “Credentials” panel. Please use the generated value to obtain a Sender ID in the Google Play Developer Portal for your app.

In order for GetSocial to send push notifications on your behalf, you need to upload the Google API key and the Sender ID in the GetSocial Dashboard.

You need to add the following permissions to your AndroidManifest.xml to allow the application to receive and display Google Cloud Messaging notifications from GetSocial.

<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" />

The custom permission is required for Google Cloud Messaging. The permission name is YOUR_PACKAGE_NAME.gcm.permission.C2D_MESSAGE where YOUR_PACKAGE_NAME is the package name declared in your AndroidManifest.xml.

<permission android:name="YOUR_PACKAGE_NAME.gcm.permission.C2D_MESSAGE" android:protectionLevel="signature" />
<uses-permission android:name="YOUR_PACKAGE_NAME.gcm.permission.C2D_MESSAGE" />

When you tap on a notification, the launcher activity of your app will be open. You can customize this behavior adding an intent filter to the action “getsocial.intent.action.NOTIFICATION_RECEIVE” to the activity that integrates the GetSocial SDK.

You must add im.getsocial.sdk.core.GetSocialReceiver to your AndroidManifest.xml for your application to register for and receive GetSocial push notifications.

<application ...>
        <receiver
            android:name="im.getsocial.sdk.core.GetSocialReceiver"
            android:permission="com.google.android.c2dm.permission.SEND" >

            <intent-filter>
                <action android:name="com.google.android.c2dm.intent.REGISTRATION" />
                <action android:name="com.google.android.c2dm.intent.RECEIVE" />
                <category android:name="YOUR_PACKAGE_NAME.gcm" />
            </intent-filter>

            <intent-filter>
                <action android:name="im.getsocial.sdk.intent.RECEIVE" />
                <data android:scheme="getSocialNotificationId"/>
            </intent-filter>
        </receiver>
</application>

Important

Don’t forget to update YOUR_PACKAGE_NAME, otherwise application installation could fail on the device

Localization

The GetSocial SDK supports multiple languages. By default the device language is used, to change it you need to set the language programmatically.

[[GetSocial sharedInstance] setLanguage:@"en"];
GetSocial.sharedInstance().language = "en"
getSocial.setLanguage("it");
getSocial.SetLanguage("it");
GetSocial.setLanguage("en", onResult, onError);

We currently support the following languages:

Language ISO Code
Chinese Simplified zh-Hans
Chinese Traditional zh-Hant
Danish da
Dutch nl
English en
French fr
German de
Icelandic is
Indonesian id
Italian it
Japanese ja
Korean ko
Malay ms
Norwegian nb
Portuguese (Brazil) pt-br
Portuguese pt
Russian ru
Spanish es
Swedish sv
Tagalog tl
Turkish tr
Vietnamese vi

Note

Take in mind that UI needs to be reloaded to reflect the language change

Integration with Facebook

The GetSocial SDK can easily interact with the Facebook social features using one of the latest versions of the Facebook SDK.

Make sure you follow the Facebook SDK integration for iOSAndroidUnity Android and Unity iOS.

UNITY 5 and FACEBOOK SDK 7.x

Facebook Unity SDK 7.x introduces a lot of API changes and support for Unity 5 and will not work in Unity 4. Make sure to read the changelog and update all your calls to Facebook API if you are upgrading from Facebook Unity SDK version 6.x

Are you compiling with iOS 9?

Don’t forget to read and follow the Facebook iOS 9 guide to make you application work properly.

Customizing Behaviours

Handling Avatar click

You can easily register a handler to override GetSocial’s default behavior while clicking on an avatar.

There are two different handlers, one for user avatars and another for the app avatar.

[[GetSocial sharedInstance] setOnAppAvatarClickHandler:^BOOL {
    // Custom code to handle the app avatar click
    // return YES to indicate that you'll handle the event, or NO if SDK should handle it
    return YES;
}];

[[GetSocial sharedInstance] setOnUserAvatarClickHandler:^BOOL(GetSocialUserIdentity* user, GetSocialSDKSourceViewEnum source) {
    // Custom code to handle the user avatar click
    // return YES to indicate that you'll handle the event, or NO if SDK should handle it
    return NO;
}];

GetSocial.sharedInstance().setOnAppAvatarClickHandler { () -> Bool in
    // custom code to handle the app avatar click
    // return 'true' to indicate that you'll handle the event, or 'false' if SDK should handle it
    return true
}

GetSocial.sharedInstance().setOnUserAvatarClickHandler { (user : GetSocialUser!, source : GetSocialSourceView) -> Bool in
    // custom code to handle the user avatar click
    // return 'true' to indicate that you'll handle the event, or 'false' if SDK should handle it
    return false
}
getSocial.setOnAppAvatarClickHandler(new GetSocial.OnAppAvatarClickHandler()
{
    @Override
    public boolean onAppAvatarClick()
    {
      // Custom code to handle the app avatar click
      // return true to indicate that you'll handle event, or false if SDK should handle it
      return true;
    }
});

getSocial.setOnUserAvatarClickHandler(new GetSocial.OnUserAvatarClickHandler()
{
    @Override
    public boolean onUserAvatarClick(String userGuid)
    {
      // Custom code to handle the user avatar click
      // return true to indicate that you'll handle event, or false if SDK should handle it
      return true;
    }
});
getSocial.SetOnAppAvatarClickListener(() => {
    // Custom code to handle the app avatar click
    // return true to indicate that you'll handle event, or false if SDK should handle it
    return true;
});

getSocial.SetOnUserAvatarClickListener((user, source) => {
    // Custom code to handle the user avatar click
    // return true to indicate that you'll handle event, or false if SDK should handle it
    return true;
});
// send true to indicate that you'll handle event, or false if SDK should handle it
GetSocial.setOnAppAvatarClickHandler(function(){
    // Custom code to handle the app avatar click
});

// send true to indicate that you'll handle event, or false if SDK should handle it
GetSocial.setOnUserAvatarClickHandler(function(guid){
    // Custom code to handle the user avatar click
});

Intercepting Actions

Each action on the GetSocial SDK can be intercepted and optionally blocked, if needed.

For example, this feature is useful if you want, to:

[[GetSocial sharedInstance]
    setOnActionPerformHandler:^(GetSocialAction action,
                                void (^finalize)(BOOL shouldPerformAction)) {

        //Here you can do any task before the GetSocial action is done
        ...
        //When you finish with your custom behaviour,
        //make sure that you always call the finalize block
        //with either YES to continue or NO to ignore the action
        finalize(YES);
    }];
GetSocial.sharedInstance().
    setOnUserActionPerformHandler({ (action: GetSocialAction,
        finalize : GetSocialFinalizeActionCallback!) -> Void in

            // Here you can do any task before the GetSocial action is done
            // ...
            // When you finish with your custom behaviour,
            // make sure that you always call the finalize block
            // with either true to continue or false to ignore the action
            finalize(true)
})
GetSocial.getInstance().setOnActionPerformListener(new GetSocial.OnActionPerformListener()
{
    @Override
    public void onActionPerform(GetSocial.Action action, ActionFinalizer actionFinalizer)
    {
        // Here you can do any task before the GetSocial action is done
        // ...
        // When you finish with your custom behavior,
        // make sure that you always call the finalize block
        // with either YES to continue or NO to ignore the action
        actionFinalizer.finalize(true);
    }
});
GetSocial.Instance.SetOnUserPerformedActionListener((action, finalizeAction) =>
{
    // Here you can do any task before the GetSocial action is done
    // ...
    // When you finish with your custom behavior,
    // make sure that you always call the finalize block
    // with either YES to continue or NO to ignore the action
    finalizeAction(true);
});
GetSocial.setOnActionPerformListener(function(action, finalizerHash) {
    // Here you can do any task before the GetSocial action is done
    / ...
    // When you finish with your custom behavior,
    // make sure that you always call the finalizeAction method
    // with either true to continue or false to ignore the action

    var continueAction = true;
    GetSocial.finalizeAction(finalizerHash, continueAction, function(success){});
});

Content Moderation

We provide automatic content moderation of activities, comments, and chats. To activate it please contact us and we will provide you some options depending on your needs.

If you need custom moderation or have access to the content sent by users inside your app, you can register for a callback. This callback will be called every time the current user wants to post some content to the activity feed or via chat (private or public rooms).

Implementing this callback allows you to verify that the content adheres to your standards and modify/refuse the content if it does not.

Content can be evaluated differently according to the ContentSource. For example, you might want to moderate messages on an Public chats, but allow any kind of messages on Private chats.

[[GetSocial sharedInstance] setOnUserGeneratedContentHandler:^NSString *(GetSocialContentSource source, NSString *content) {
    NSString* approvedContent = [content stringByReplacingOccurrencesOfString:@"SoftBadWord"
        withString:@"*****"];

    if ([approvedContent rangeOfString:@"HardBadWord"].location != NSNotFound)
    {
        approvedContent = nil;
    }
    return approvedContent;
}];
GetSocial.sharedInstance().setOnUserGeneratedContentHandler({ (source: GetSocialContentSource, content : String!) -> String! in
    var approvedContent = content.stringByReplacingOccurrencesOfString("SoftBadWord", withString: "*****")
    if(approvedContent.containsString("HardBadWord")){
        approvedContent = ""
    }
    return approvedContent
})
getSocial.setOnUserGeneratedContentListener(new GetSocial.OnUserGeneratedContentListener()
{
    @Override
    public String onUserGeneratedContent(GetSocial.ContentSource source, String content)
    {
        if(content.contains("HardBadWord"))
        {
            return null;
        }
        else
        {
            return content.replace("SoftBadWord", "*****");
        }
    }
});
getSocial.SetOnUserGeneratedContentListener((source, content) => {
    content = content.Replace("SoftBadWord", "*****");
    if (content.Contains("HardBadWord"))
    {
        return null;
    }
    else
    {
        return content;
    }
});

Note

Currently clientside Content Moderation is not available in Cordova SDK.

Customizing Appearance

GetSocial is a fully white label solution; you can customize the UI to match the look and feel of your app.

Check the UI Customization guide to learn more.

Webhooks

Our webhook system allows you to receive smart invites related events in real time, for invite attribution in your own database. You simply need to specify a URL for us to send all this data to.

App install Event

This event is posted as soon as the app get installed and is open for the first time as a result of a smart invite.

POST
User-agent: GetSocial API
Content-Type: application/json
{
//type of event
    "event": "app_install",

//event details of the smart invite
    "provider": "email",
    "id": "roAsoT",

//custom data added when generating the smart invite
    "customKey": "customValue",

//details from the receiver
    "model": "iPhone8,1",
    "device_language": "en-US",
    "manufacturer": "Apple",
    "screen_width": 640,
    "screen_height": 1136,
    "os": "iOS",
    "os_version": "9.3",
    "carrier": "Carrier",
    "ifv": "C258B711-E211-4303-B319-BF09E3707A87",
    "idfa": "97D86B54-B785-4036-A83C-B9F58A4CEF1C",
    "ip_address": "83.86.93.133",
    "user_guid": "6891816211873840179",

//details of the referrer (sender)
    "referrer_user_guid": "6132096813920178831",
    "referrer_idfa": "24E9BA0B-4217-4F6D-A22B-77B7167482DB",
    "referrer_user": {
        "facebook": "130436773967888"
    }
}

Referral data received event

This event is posted as soon as the app is opened as a result of clicking on a smart invite link if the app was already installed or after installing it.

POST
User-agent: GetSocial API
Content-Type: application/json
{
//type of event
    "event": "referral_data_received",

//event details of the smart invite
    "provider": "email",
    "id": "roAsoT",

//indicates if the data is being sent to the receiver for the first time
    "first_match": false,

//custom data added when generating the smart invite
    "customKey": "customValue",

//details from the receiver
    "user_guid": "6891816211873840179",

//details of the referrer (sender)
    "referrer_user_guid": "6132096813920178831",
    "referrer_idfa": "24E9BA0B-4217-4F6D-A22B-77B7167482DB",
    "referrer_user": {
        "facebook": "130436773967888"
    }
}

Register Webhook on Dashboard

To register a webhook on the dashboard, open up GetSocial Dashboard, login with your account and click on the ‘Webhooks’ option.

Enter Your Webhook URL and press Save.

Using Requestb.in to test the webhook

Now you should have a dedicated URL that you can use to simulate your server.

The next step is to set up your webhook with GetSocial. Navigate to the GetSocial Dashboard and click “Webhooks”.

Now you should copy your URL from RequestBin into the text field with the label “URL” and save the changes.

Now every time someone installs the app using our smart invite, the webhook you’ve configured on GetSocial will send a request to your RequestBin, give it a try.

Verifying Webhook Requests

Webhook requests made by GetSocial servers include two headers, X-Getsocial-Id and X-Getsocial-Signature. Every request is given a unique ID and it’s sent via the X-Getsocial-Id header. You can store this ID to prevent duplicates and replay attacks.

You can (and should) use the X-Getsocial-Signature header to verify the origin and integrity of the webhook payload. The signature is the SHA256 hash of the payload, in lowercase hexits, using the Shared Secret in your GetSocial Dashboard as the key. Here’s a sample verification code in PHP:

$body = file_get_contents('php://input');
$hash = hash_hmac('sha256', $body, $sharedSecret);
if (hash_equals($hash, $_SERVER['HTTP_X_GETSOCIAL_SIGNATURE'])) {
  // Valid signature
} else {
  // Invalid signature
}

Webhook Policies

We expect your webhook endpoint to respond with a 200 OK status within 5 seconds. Any other situation is considered to be a failure.

When a failure is encountered, we stop sending requests and retry again after a short delay. This delay starts with 1 second and increases gradually up to 1 minute. At that point, we keep retrying every 60 seconds.