Skip to main content

Getting Started

You're 3 steps away from adding great in-app support to your Cocos2dx Game.

Requirements

  • Xcode 12.0 and above.
  • Supported iOS versions - iOS 13 and above
  • Supported Android versions - API level 24 and above i.e Android OS 7 Nougat and above.
  • Cocos2dx 3.x and above
Note
  • Update (August 2023): SDK X 10.2.x is functional only above API Level 24 i.e Android OS 7 Nougat and above.
  • SDK 10.3.0 functions and is supported on Android 7 and above (API level 24 and above). You can still compile your app using a minimum API level of 16, but the support starts for API level 24 and above. For details regarding Helpshift SDK's Android OS support policy, please refer to this article.

Step 1 - Download the Cocos2d-x plugin for Helpshift​

The Helpshift SDK X Cocos package contains the following files:

android/ClassesPlugin files specific to android platform
android/proj.androidAndroid build support files
android/proj.android-studioAndroid SDK X Package
android/src/com/helpshiftAndroid Proxy classes
ios/ClassesPlugin files specific to iOS platform
iOS/sdkiOS SDK X Framework

Step 2 - Add Helpshift Plugin to your Cocos2dx project​

  1. Copy the android/src/com/helpshift folder to the src/com/ folder of Android project of your Cococs2dx game.

  2. Copy the contents of the android/Classes folder to the Classes folder of your Cocos2dx game.

Add Helpshift dependencies in your project​

If you are on SDK X or migrating to SDK X please note the following requirements:

  • SDK X is functional only above API Level 24 i.e Android OS 7 Nougat and above.
  • The minSDKVersion in code is kept as API Level 16 to allow importing the SDK and compiling in apps that allow installation till API Level 16 i.e Android 4.4 Jelly Bean.
  • If your app is installed on a device below API level 24 (i.e below Android OS 7 Nougat) then you can choose to have a different medium for providing support. For example, Email, Web etc. We throw an UnsupportedOSVersionException if the SDK is initialized below API Level 24. Please catch and use this exception according to your needs. Refer: Initializing the SDK.

  1. Copy the Helpshift.aar file from the android/proj.android-studio/libs present inside plugin folder to the libs directory of your android project.

  2. Add dependency to Helpshift SDK in your app/build.gradle file.

repositories {
    //your other repositories
    flatDir { dirs 'libs' }
}

dependencies {
    // your other dependencies

    implementation 'androidx.appcompat:appcompat:1.0.0'
    implementation(name: 'Helpshift', ext:'aar')
}
  1. Link Helpshift files in your project as source depending on your build system.
# Add Helpshift files to CMakeLists.txt, under the Android dependency
if(ANDROID)
  list(APPEND GAME_SOURCE
       <other dependency files>
       Classes/HelpshiftCocos2dx.cpp
       Classes/HelpshiftUtil.cpp
       Classes/HelpshiftLog.cpp
       )
  list(APPEND GAME_HEADER
      <other dependency files>
      Classes/HelpshiftCocos2dx.h
      Classes/HelpshiftUtil.h
      Classes/HelpshiftLog.h
      Classes/HelpshiftEvent.h
      )
endif()

Step 3 - Initialize Helpshift in your game​

  1. First, create a game on the Helpshift Dashboard

  2. Create a game with Android and iOS as a selected Platform

Helpshift uniquely identifies each registered game with a combination of 2 tokens:

Platform IDYour Games's unique App Id (Games's App Id on dashboard is your platform Id)
Domain NameYour Helpshift domain. E.g. happyapps.helpshift.com

To obtain these values:

  1. Go to your Helpshift dashboard
  2. Navigate to Settings > SDKs (for Developers)
  3. Select your Game and from the dropdowns
  4. Copy the two tokens present in the "Android" table

Initialize Helpshift by importing com.helpshift.HelpshiftCocosBridge and calling the HelpshiftCocosBridge.install in the onCreate of your Cocos2dxActivity:

import com.helpshift.HelpshiftCocosBridge;

public class MyActivity extends Cocos2dxActivity {

    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        // Add install configs in the config map
        Map<String, Object> config = new HashMap<>();
        //...
        // Install call
        HelpshiftCocosBridge.install(
            this,
            "<App Id from the Helpshift Dashboard>",
            "<Domain name from the Helpshift Dashboard>",
            config);
    }
}

Initializing Helpshift in your game for China​

A special install config key, isForChina, should be used for integrating Helphift SDK for China region. This config key accepts a boolean value. Pass true if you are integrating the SDK in an game for China region. The value defaults to false if left unspecified.

import com.helpshift.HelpshiftCocosBridge;

public class MyActivity extends Cocos2dxActivity {

    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        Map<String, Object> config = new HashMap<>();
        config.put("isForChina", true);

        // Install call
        HelpshiftCocosBridge.install(
            this,
            "<App Id from the Helpshift Dashboard>",
            "<Domain name from the Helpshift Dashboard>",
            config);
    }
}
Important

Placing the install call

Use HelpshiftCocosBridge.install(...); with the required arguments immediately after the super.onCreate() of your Cocos2dx Activity. Placing it elsewhere might cause unexpected runtime problems.

HelpshiftInitializationException

Calling any API before the install call would throw an unchecked HelpshiftInitializationException in debug mode.

UnsupportedOSVersionException

Calling install() below Android SDK version 24 will throw this checked exception. All the APIs will be non operable.