Getting started with Unity

1. REQUIREMENTS

  • Unity 3. Last version verified: 3.5.6f4
  • Target platform: iOS/Android

2. DOWNLOAD THE GEOSOPHIC SDK PLUGIN FOR UNITY

Latest versions of the Geosophic SDKs can be found Here.

3. SET UP GEOSOPHIC SDK PLUGIN FOR YOUR PROJECT

Integrate the plugin with the SDK in your project by following these steps:

  1. Import the Geosophic unitypackage file in your project. Right click in the Project tab –> Import package –> Custom package.
  2. Add the GeosophicPlugin prefab (blue cube icon) to your first scene “Hierarchy” tab by dragging it there.

4. CONNECT YOUR GAME TO YOUR GEOSOPHIC ACCOUNT

Set up the connection settings for Geosophic in your project:

  1. Go to the Geosophic developer dashboard and browse to your game. Select “Settings” and copy the values of the “Connection Settings” section. Open the geosophicsdk.properties file located into the Android/assets folder and paste the “Connection Settings” values of your account.
  2. For iOS:
    1. Build your iOS project as usual and all the resources needed by Geosophic will be included in the XCode project automatically.
    2. If you want to run the project in the iOS simulator you have to change the RegisterMonoModules.cpp file:
      • In the first extern “C” section, move the mono_dl_register_system outside the if-endif section
      • In the RegisterMonoModules definition, move the “mono_dl_register_symbol(“_GPCUnityBridge_sendMessage”, (void*)&_GPCUnityBridge_sendMessage)” line outside the if-endif section
  3. For Android:
    1. Add the following fields to your custom AndroidManifest.xml. You can use the predefined manifest, included in the plugin, as a guide:
      • Include these permissions:
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
      • Include Geosophic’s View activity
<activity android:name="com.geosophic.view.Geosophic_View"
android:configChanges="orientation|keyboardHidden|screenSize"
android:theme="@android:style/Theme.NoTitleBar">
</activity>
      • Include Geosophic’s services
<service android:name="org.openudid.Geosophic_OpenUDID_service">
  <intent-filter>
    <action android:name="org.openudid.GETUDID" />
  </intent-filter>
</service>

That’s all. Now you are able to use the Geosophic SDK calls inside your Unity project.

5. USING GEOSOPHIC FEATURES IN YOUR GAME

 

Check if the Geosophic’s service is active

To check the service you must call the method:

void isGeosophicServiceActive()

You can subscribe to the following call events:

  • OnGeosophicServiceInitialized: This event is fired when the Geosophic’s service is initialized.
  • OnGeosophicServiceStopped: This event is fired when the Geosophic’s service is stopped.
  • OnGeosophicServiceStatusGet: This event is fired when isGeosophicServiceActive() is called. This event receives a Boolean parameter that indicates if the Geosophic’s service is active or not.

Example:

void serviceChecker (Boolean done)
{
  if (done) {
    // Service active...
  } else {
    // Service not active... 
  }
}

void OnEnable() {
GeosophicSDK.OnGeosophicServiceStatusGet += serviceChecker;
}

void OnDisable() {
GeosophicSDK.OnGeosophicServiceStatusGet -= serviceChecker;
}

void OnGUI() {
if (GUI.Button(new Rect(10, 10, 200, 200), “Check service”)) {
GeosophicSDK.isGeosophicServiceActive();
}
}

USE CASE: Post player scores or votes and view leaderboards

Check how our location based leaderboards work before you use them.

Submit a player score

To post a score you must call the method:

void PostScore (int score, int leaderBoardSchema)
score: Value of the score.
leaderboardSchemaId: Identifier of the leaderboard you want to submit the score. You can get this id in the “Settings” view of your game.

You can subscribe to the following call events:

  • OnBeginScorePost: This event is fired before the call is processed by the SDK.
  • OnEndScorePost: This event is fired when the SDK receives the response of the call. This event receives the following parameters:
    • done: A boolean that notifies if the call is processed by the SDK or not. True if it’s processed and false in other case (no internet connection, bad parameters, …).
    • response: A GPCScoreResponse object (take a look GPCScoreResponse.cs) when the call is processed and null in other case. This object has two variables:
      highScore: True if the score submitted is a new personal highscore.
      leaderboardId: Id of the leaderboard where the score has been submitted.
    • leaderboardSchema: A integer that represents the schema where you post the score.
    • errorMessage: A string that contains the cause of a fail call when the done variable is false.

Example:

void scoreReceiver (Boolean done, GPCScoreResponse response, int leaderboardSchema, String errorMessage)
{
  if (done) {
    // Do some work...
  } else {
    // Error
  }
}

void callMade()
{
Debug.Log(“Post score done”);
}

void OnEnable() {
GeosophicSDK.OnBeginScorePost += callMade;
GeosophicSDK.OnEndScorePost += scoreReceiver;
}

void OnDisable() {
GeosophicSDK.OnBeginScorePost -= callMade;
GeosophicSDK.OnEndScorePost -= scoreReceiver;
}

void OnGUI() {
if (GUI.Button(new Rect(10, 10, 200, 200), “Post score”)) {
GeosophicSDK.PostScore (100, 303);
}
}

Display a leaderboard

There are two ways to get the contents of a leaderboard in a predefined HTML view.

void ShowLeaderboard (int leaderboardId, int leaderboardSchema) 
void ShowLeaderboard (int leaderboardSchema)
leaderboardId: Identifier of the leaderboard you want to display. The device’s nearest location is showed when you call to the view without the leaderboardId parameter.
leaderboardSchema: Identifier of the leaderboardSchema you are using. You get this id in the “Settings” page of your game.

You can subscribe to the following call events:

  • OnLBViewInitialized: This event is fired before the call is processed by the SDK.
  • OnLBViewPresented: This event is fired when the dashboard appears in the screen. This event receives the following parameters:
    • done: A boolean that notifies if the dashboard is presented or not. True if it’s presented and false in other case (bad parameters, …).
    • errorMessage: A string that contains the cause of a fail call when the done variable is false.
  • OnLBViewClosed: This event is fired when the dashboard is closed.

A sample call like

void logInitialized()
{
  Debug.Log("Try to show the leaderboard");
}

void logPresented(Boolean done, String errorMessage)
{
if (done)
Debug.Log(“Dashboard presented”);
else
Debug.Log(“Error:” + errorMessage);
}

void logClosed()
{
Debug.Log(“The dashboard is closed”);
}

void OnEnable() {
GeosophicSDK.OnLBViewInitialized += logInitialized;
GeosophicSDK.OnLBViewPresented += logPresented;
GeosophicSDK.OnLBViewClosed += logClosed;
}

void OnDisable() {
GeosophicSDK.OnLBViewInitialized -= logInitialized;
GeosophicSDK.OnLBViewPresented -= logPresented;
GeosophicSDK.OnLBViewClosed -= logClosed;
}

void OnGUI() {
if (GUI.Button(new Rect(10,10,200,200), “Show leaderboard)) {
GeosophicSDK.ShowLeaderboard(303);
}
}

will display the nearest leaderboard.

Submit a player vote

To post a vote you must call the method:

void PostVote (String choice, int leaderBoardSchema)
choice: Value of the score.
leaderboardSchema: Identifier of the leaderboard you want to submit the vote. You can get this id in the “Settings” view of your game.

You can subscribe to the following call events:

  • OnBeginVotePost: This event is fired before the call is processed by the SDK.
  • OnEndVotePost: This event is fired when the SDK receives the response of the call. This event receives the following parameters:
    • done: A boolean that notifies if the call is processed by the SDK or not. True if it’s processed and false in other case (no internet connection, bad parameters, …).
    • response: A GPCVoteResponse object (take a look GPCVoteResponse.cs) when the call is processed and null in other case. This object has two variables:
      choice: The last vote posted in the leaderboard by the player.

      firstCast: True if this vote was the first vote of the player, false in other case.

      leaderboardSchema: Schema of the leaderboard where the vote has been submitted.
    • errorMessage: A string that contains the cause of a fail call when the done variable is false.

Example:

void voteReceiver (Boolean done, GPCVoteResponse response, String errorMessage)
{
  if (done) {
    // Do some work...
  } else {
    // Error
  }
}

void callMade()
{
Debug.Log(“Post score done”);
}

void OnEnable() {
GeosophicSDK.OnBeginVotePost += callMade;
GeosophicSDK.OnEndVotePost += voteReceiver;
}

void OnDisable() {
GeosophicSDK.OnBeginVotePost -= callMade;
GeosophicSDK.OnEndVotePost -= voteReceiver;
}

void OnGUI() {
if (GUI.Button(new Rect(10, 10, 200, 200), “Post score”)) {
GeosophicSDK.PostVote (“Candidate 1″, 303);
}
}

Get a player vote info

To get a player vote info you must call the method:

void GetUserVote (int leaderBoardSchema)
leaderboardSchema: Identifier of the leaderboard which you want to obtain the vote info. You can get this id in the “Settings” view of your game.

You can subscribe to the following call events:

  • OnBeginUserVoteGet: This event is fired before the call is processed by the SDK.
  • OnEndUserVoteGet: This event is fired when the SDK receives the response of the call. This event receives the following parameters:
    • done: A boolean that notifies if the call is processed by the SDK or not. True if it’s processed and false in other case (no internet connection, bad parameters, …).
    • response: A GPCVoteResponse object (take a look GPCVoteResponse.cs) when the call is processed and null in other case. This object has two variables:
      choice: The last vote posted in the leaderboard by the player.

      firstCastTrue if this vote was the first vote of the player, false in other case.

      leaderboardSchema: Schema of the leaderboard where the vote has been submitted.
    • errorMessage: A string that contains the cause of a fail call when the done variable is false.

Example:

void voteReceiver (Boolean done, GPCVoteResponse response, String errorMessage)
{
  if (done) {
    // Do some work...
  } else {
    // Error
  }
}

void callMade()
{
Debug.Log(“Post score done”);
}

void OnEnable() {
GeosophicSDK.OnBeginUserVoteGet += callMade;
GeosophicSDK.OnEndUserVoteGet += voteReceiver;
}

void OnDisable() {
GeosophicSDK.OnBeginUserVoteGet -= callMade;
GeosophicSDK.OnEndUserVoteGet -= voteReceiver;
}

void OnGUI() {
if (GUI.Button(new Rect(10, 10, 200, 200), “Post score”)) {
GeosophicSDK.GetUserVote (303);
}
}

Display a voting leaderboard

There are two ways to get the contents of a voting leaderboard in a predefined HTML view.

void ShowVotingLeaderboard (int leaderboardId, int leaderboardSchema) 
void ShowVotingLeaderboard (int leaderboardSchema)
leaderboardId: Identifier of the leaderboard you want to display. The device’s nearest location is showed when you call to the view without the leaderboardId parameter.
leaderboardSchema: Identifier of the leaderboardSchema you are using. You get this id in the “Settings” page of your game.

You can subscribe to the following call events:

  • OnLBViewInitialized: This event is fired before the call is processed by the SDK.
  • OnLBViewPresented: This event is fired when the dashboard appears in the screen. This event receives the following parameters:
    • done: A boolean that notifies if the dashboard is presented or not. True if it’s presented and false in other case (bad parameters, …).
    • errorMessage: A string that contains the cause of a fail call when the done variable is false.
  • OnLBViewClosed: This event is fired when the dashboard is closed.

A sample call like

void logInitialized()
{
  Debug.Log("Try to show the leaderboard");
}

void logPresented(Boolean done, String errorMessage)
{
if (done)
Debug.Log(“Dashboard presented”);
else
Debug.Log(“Error:” + errorMessage);
}

void logClosed()
{
Debug.Log(“The dashboard is closed”);
}

void OnEnable() {
GeosophicSDK.OnLBViewInitialized += logInitialized;
GeosophicSDK.OnLBViewPresented += logPresented;
GeosophicSDK.OnLBViewClosed += logClosed;
}

void OnDisable() {
GeosophicSDK.OnLBViewInitialized -= logInitialized;
GeosophicSDK.OnLBViewPresented -= logPresented;
GeosophicSDK.OnLBViewClosed -= logClosed;
}

void OnGUI() {
if (GUI.Button(new Rect(10,10,200,200), “Show leaderboard)) {
GeosophicSDK.ShowVotingLeaderboardView(303);
}
}

will display the nearest leaderboard.

USE CASE: Set player’s nickname

Each player has an unique nickname in Geosophic. Geosophic’s service sets a nickname, using the “PLAYER_NUMBER” format, to each player by default. To change or update the player’s nickname you must call the method:

void UpdateNickname (String nickname)
nickname: The new nickname of the player.   

You can subscribe to the following call events:

  • OnBeginNicknameUpdate: This event is fired before the call is processed by the SDK.
  • OnEndNicknameUpdate: This event is fired when the SDK receives the response of the call. This event receives the following parameters:
      • done: A boolean that notifies if the call is processed by the SDK or not. True if it’s processed and false in other case (no internet connection, bad parameters, …).
      • response: A GPCNicknameResponse object (take a look GPCNicknameResponse.cs) when the call is processed and null in other case. This object contains the following information:
        • isNicknameUpdated: Returns if the user nickname is available. If it re
          turns true, the nickname is available and set. If it returns false, the nickname is in use by another player so you have to choose another one.
        • getSuggestedNickname: If your requested nickname is in already in use, calling this method you’ll get a suggestion of an available nickname. It is not mandatory to use this one in a new update nickname call.
      • errorMessage: A string that contains the cause of a failed call when the done variable is false.

A sample call like

void nicknameReceiver (Boolean done, GPCNicknameResponse response, String errorMessage)
{
  if (done) {
    if (response.isNicknameUpdated()) {
      // Do some work...
    }  else {
      GeosophicSDK.UpdateNickname (response.getSuggestedNickname ());
    }
  } else
    // Error
}

void logCall()
{
Debug.Log(“Call made”);
}

void OnEnable() {
GeosophicSDK.OnBeginNicknameUpdate += logCall;
GeosophicSDK.OnEndNicknameUpdate += nicknameReceiver;
}

void OnDisable() {
GeosophicSDK.OnBeginNicknameUpdate -= logCall;
GeosophicSDK.OnEndNicknameUpdate -= nicknameReceiver;
}

void OnGUI() {
if (GUI.Button(new Rect(10, 10, 200, 200), “Update nickname”)) {
GeosophicSDK.UpdateNickname (“nickname”);
}
}

USE CASE: Get player’s nickname

To get the player’s nickname you must call the method:

void GetPlayerNickname ()

You can subscribe to the following call events:

  • OnBeginPlayerNicknameGet: This event is fired before the call is processed by the SDK.
  • OnEndPlayerNicknameGet: This event is fired when the SDK receives the response of the call. This event receives the following parameters:
    • done: A boolean that notifies if the call is processed by the SDK or not. True if it’s processed and false in other case (no internet connection, bad parameters, …).
    • nickname: A String with the player’s nickname.
    • errorMessage: A string that contains the cause of a failed call when the done variable is false.

A sample call:

void getNicknameReceiver (Boolean done, String nickname, String errorMessage) {
    //Do some work...
}

void OnEnable() {
GeosophicSDK.OnEndPlayerNicknameGet += getNicknameReceiver;
}

void OnDisable() {
GeosophicSDK.OnEndPlayerNicknameGet -= getNicknameReceiver;
}

void OnGUI() {
if (GUI.Button(new Rect(10, 10, 200, 200), “Get nickname”)) {
GeosophicSDK.GetPlayerNickname();
}
}

USE CASE: Get player’s highscores

To get the player’s global highscores in your game you must call the method:

void GetPlayerHighscores ()

You can subscribe to the following call events:

  • OnBeginPlayerHighscoreGet: This event is fired before the call is processed by the SDK.
  • OnEndPlayerHighscoreGet: This event is fired when the SDK receives the response of the call. This event receives the following parameters:
    • done: A boolean that notifies if the call is processed by the SDK or not. True if it’s processed and false in other case (no internet connection, bad parameters, …).
    • response: An ArrayList with the player’s highscores. The object contains an array of Hashtable objects which represents the highscores of the player in each leaderboard schema defined in your game. Schemas which don’t have a score associated to the player are not included in the array. So if the player doesn’t have any score in any leaderboard the array is empty.The fields of the Hashtable are:
      • leaderboardSchemaId: Value of the leaderboard schema associated to this highscore.
      • rank: Worldwide ranking of the player.
      • value: Value of the highscore.
    • errorMessage: A string that contains the cause of a failed call when the done variable is false.

An example of array returned by this call:

[{"leaderboardSchemaId" : 567, "rank" : 2, "value" : "600.0"},{"leaderboardSchemaId" : 625, "rank" : 3, "value" : "740.0"},{"leaderboardSchemaId" : 340, "rank" : 4, "value" : "720.0"}]

The use of the call is as simple as

void getHighscoreReceiver (Boolean done, ArrayList highscores, String errorMessage){
    //Do some work...
}

void OnEnable() {
GeosophicSDK.OnEndPlayerHighscoreGet += getHighscoreReceiver;
}

void OnDisable() {
GeosophicSDK.OnEndPlayerHighscoreGet -= getHighscoreReceiver;
}

void OnGUI() {
if (GUI.Button(new Rect(10, 10, 200, 200), “Get player highscores”)) {
GeosophicSDK.GetPlayerHighscores();
}
}

USE CASE: Get player’s ranking for the nearest leaderboard

To get the player’s ranking for the nearest leaderboard to the current location you must call the method:

void GetPlayerRank (int leaderboardSchema, int neighbours)
leaderboardSchema: Identifier of the leaderboard schema.
neighbours: This value allows you to include data of the players that precede and follow the current player in the ranking. Zero to not include data of other players.

You can subscribe to the following call events:

  • OnBeginPlayerRankGet: This event is fired before the call is processed by the SDK.
  • OnEndPlayerRankGet: This event is fired when the SDK receives the response of the call. This event receives the following parameters:
    • done: A boolean that notifies if the call is processed by the SDK or not. True if it’s processed and false in other case (no internet connection, bad parameters, …).
    • response: An ArrayList with the player’s highscores. The object contains an array of Hashtables which represents the info of the leaderboards associated to the current location. If the location is disabled the array just contains info of the worldwide leaderboard.The fields of the Hashtable are:
      • latitude: Latitude of the leaderboard.
      • longitude: Longitude of the leaderboard.
      • placeName: Name of the location linked to the leaderboard.
      • playerInfo: Hashtable with the info of the player. If the player doesn’t have any score uploaded into the leaderboard, this field is not included.
        • scoreDate: Date where the highscore was uploaded.
        • scoreValue: Value of the highscore.
        • userNickname: Nickname of the player.
        • userRank: Player ranking in this leaderboard
      • ranking: ArrayList of Hashtables that contains the ranking of the player and the neighbours. The array is ordered by ranking. If the player doesn’t have any score uploaded into the leaderboard, this field is not included. Each Hashtable contains the same fields as the playerInfo object showed previous
    • errorMessage: A string that contains the cause of a failed call when the done variable is false.
[
  {
   "latitude" : 0,
   "longitude" : 0,
   "placeName" : "World",
   "playerInfo" :         
   {
     "scoreDate" : 1360732096087,
     "scoreValue" : 600,
     "userNickname" : "Player2",
     "userRank" : 2
    },
    "ranking" : [
     {
      "scoreDate" : 1360732096086,
      "scoreValue" : 1540,
      "userNickname" : "Player0",
      "userRank" : 0
     },
     {
      "scoreDate" : 1360732096087,
      "scoreValue" : 1415,
      "userNickname" : "Player1",
      "userRank" : 1
     },
     {
      "scoreDate" : 1360732096087,
      "scoreValue" : 600,
      "userNickname" : "Player2",
      "userRank" : 2
     },
     {
      "scoreDate" : 1360732096088,
      "scoreValue" : 400,
      "userNickname" : "Player3",
      "userRank" : 3
     },
     {
      "scoreDate" : 1360732096088,
      "scoreValue" : 120,
      "userNickname" : "Player4",
      "userRank" : 4
     }]
  },
  {
   "latitude" : "52.1082",
   "longitude" : "5.32986",
   "placeName" : "Netherlands"
  },
  {
   "latitude" : "52.582619",
   "longitude" : "4.93554",
   "placeName" : "North Holland"
  },
  {
   "latitude" : "52.373119",
   "longitude" : "4.89319",
   "placeName" : "Amsterdam"
  }
]
A call example

void getRankReceiver (Boolean done, ArrayList response, String errorMessage)
{
  if (done) {
    Debug.Log ("Get rank call done");
    Debug.Log ("Response items: " + response.Count);
    for (int i = 0; i < response.Count; i++) {
      Hashtable rankInfo = (Hashtable)response [i];
      Debug.Log ("Latitude: " + rankInfo["latitude"]);
    }
  } else {
    Debug.Log ("Get rank call error: " + errorMessage);
  }  
}

void OnEnable() {
GeosophicSDK.OnEndPlayerRankGet += getRankReceiver;
}

void OnDisable() {
GeosophicSDK.OnEndPlayerRankGet -= getRankReceiver;
}

void OnGUI() {
if (GUI.Button(new Rect(10, 10, 200, 200), “Get player rank”)) {
GeosophicSDK.GetPlayerRank(303, 2);
}
}

USE CASE: Track custom events

You can track custom in-game events like finishing a level, using a power-up or purchasing an item with this feature.

void SendUserEvent (string eventName, Hashtable data)
eventName: Name that identifies the event.
data: Map of parameters to associate with the event. The objects in this map have to be serializable.

You can subscribe to the following call events:

  • OnBeginUserEventPost: This event is fired before the call is processed by the SDK.
  • OnEndUserEventPost: This event is fired when the SDK receives the response of the call. This event receives the following parameters:
    • done: A boolean that notifies if the call is processed by the SDK or not. True if it’s processed and false in other case (no internet connection, bad parameters, …).
    • errorMessage: A string that contains the cause of a fail call when the done variable is false.

Sample usage:

void callLog(Boolean done, String errorMessage)
{
  //Do some work...
}

void OnEnable() {
GeosophicSDK.OnEndUserEventPost += callLog;
}

void OnDisable() {
GeosophicSDK.OnEndUserEventPost -= callLog;
}

void OnGUI() {
Hashtable data = new Hashtable(); data.Add(“Level”, “17″); data.Add(“Time”, “2:25″);

if (GUI.Button(new Rect(10, 10, 200, 200), “Post data”)) { GeosophicSDK.SendUserEvent(“Level finished”, data);
}
}

 

USE CASE: Use custom user account

Now players can access their scores and data from different devices. In order to do that, you need to connect the running instance with your custom User Id.

static public void SetCustomUserId (String customUserId);
customUserId: Custom User Id. A user id unique to the users space of the developer.

Sample usage:

void callLog(Boolean done, String errorMessage)
{
  //Do some work...
}

void OnEnable() {
GeosophicSDK.OnEndSetCustomUserId += callLog;
}

void OnDisable() {
GeosophicSDK.OnEndSetCustomUserId -= callLog;
}

void OnGUI() {
Hashtable data = new Hashtable();
if (GUI.Button(new Rect(10, 10, 200, 200), “Connect with Custom User Id”)) { GeosophicSDK.SetCustomUserId(MyUserAccount.getUserId());
}
}