Getting Started Android

Cocos2d-x plugin for Helpshift SDK helps you utilize Helpshift from your game's C++ codebase.

From version 3.2.0 and above, the Helpshift class has been renamed to HelpshiftCocos2dx. Please rename all instances of the Helpshift in your code as follows:

// Helpshift:showConversation();
// ^ the above API call becomes
HelpshiftCocos2dx::showConversation();

Guide to integrating the Cocos2d-x plugin for the Helpshift SDK which you can call from your C++ game scripts.

Download the Cocos2d-x plugin for Helpshift

Helpshift Cocos2d-x package comes in two variants:

1. Standard SDK - In-app Customer Service

Download SDK v5.0.0

2. Campaigns-enabled SDK - Proactive In-app Customer Service

Download SDK v5.0.0-withCampaigns

The Helpshift SDK plugin contains the following:

android_libs
The dependencies which the Helpshift Android SDK needs. Currently these include : design, recyclerview, appcompat, cardview
v3.x
Folder containing the files for Cocos2dx version 3.x
v2.x
Folder containing the files for Cocos2dx version 2.x

Add Helpshift to your Cocos2dx project

Copy the helpshift-plugin-cocos2dx folder to the root directory of your project.

Adding the Helpshift Android plugin / #adding-android

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

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

Using Android Studio (Only for Cocos2d-x v3.x)

  1. Create libs directory in proj.android-studio/app directory

  2. Copy the Helpshift.aar file from the android/proj.android-studio in the libs directory.

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

    repositories {
        //your other repositories
        flatDir { dirs 'libs' }
    }
    
    dependencies {
        // your other dependencies
        implementation 'com.android.support:design:28.0.0'
        implementation 'com.android.support:recyclerview-v7:28.0.0'
        implementation 'com.android.support:cardview-v7:28.0.0'
        implementation(name: 'Helpshift', ext:'aar')
    }
    
  4. Add Helpshift files to makefile (Android.mk), under the LOCAL_SRC_FILES rule. For example:

    LOCAL_SRC_FILES := hellocpp/main.cpp \
                  ../../../Classes/HelpshiftCocos2dx.cpp \
                  ../../../Classes/HelpshiftCocos2dxCampaigns.cpp \
                  ../../../Classes/HelpshiftUtil.cpp \
                  ../../../Classes/HelpshiftCocos2dxUser.cpp
    

    Add HelpshiftCocos2dxCampaigns.cpp file only if you are using Campaigns-enabled SDK.

Using Eclipse project (ANT build)

  1. To use the latest Cocos2dx plugin in your application, add a reference to the Helpshift Android SDK from the project.properties file of your Android application. With the release of version 5.0.0, the Helpshift Android plugin sets the Android target to 26. To use this plugin, set the target to android-26 in your application.

    Cocos2d-x v3.x

    android.library.reference.1=../helpshift-plugin-cocos2dx/v3.x/android/proj.android/sdk/
    

    Cocos2d-x v2.x

    android.library.reference.1=../helpshift-plugin-cocos2dx/v2.x/android/sdk/
    
  2. Add Helpshift files to makefile (Android.mk), under the LOCAL_SRC_FILES rule. For example:

    LOCAL_SRC_FILES := hellocpp/main.cpp \
                  ../../Classes/HelpshiftCocos2dx.cpp \
                  ../../Classes/HelpshiftCocos2dxCampaigns.cpp \
                  ../../Classes/HelpshiftUtil.cpp \
                  ../../Classes/HelpshiftCocos2dxUser.cpp
    

    Add HelpshiftCocos2dxCampaigns.cpp file only if you are using Campaigns-enabled SDK/

  3. Open AndroidManifest.xml located at helpshift-plugin-cocos2dx/v2.x/android/sdk/ and helpshift-plugin-cocos2dx/v3.x/android/sdk/ for Cocos2dx version 2.x and 3.x respectively. Look for ${applicationId} located in provider tag and replace it with the package name of your android app. As an example, if your appplication's package name is com.example.application, <provider> tag will now look like this:

    <provider
        android:name="com.helpshift.support.providers.HelpshiftFileProvider"
        android:authorities="com.example.application.helpshift.fileprovider"
        android:exported="false"
        android:grantUriPermissions="true" >
        <meta-data
            android:name="android.support.FILE_PROVIDER_PATHS"
            android:resource="@xml/hs__provider_paths" />
    </provider>
    
  4. Set the flag for manifestmerger.enabled to true in your project.properties file:

    manifestmerger.enabled=true
    
  5. Copy the hs__data file from the sdk/assets/ directory to the assets directory of your Cocos2dx application.

Helpshift Cocos plugin version 1.4.0 and above is packaged with the required android support libs v23.4.0 and it is also tested with Android Nougat devices.

If the developer wants to integrate android support libs 24.x, there are reported issues on pre-lolipop devices. Refer this blog and the issue here. Cocos ant build system does not support android build options for the vector changes introduced in 24.x version.

As a result, the Helpshift Cocos plugin which is tested with 24.x support lib version, does not work on pre-lollipop devices because of the Cocos ant and android build incompatibility.

Initializing Helpshift in your app

Use Helpshift.install(...); with the required arguments immediately after the super.onCreate() of your Cocos2d-xActivity.

Helpshift SDK uniquely identifies your App with the combination of:

API Key
Your unique developer API Key.
Domain Name
Your Helpshift domain name. For example : foo.helpshift.com
App ID
A unique ID assigned to your app.

To get the API Key, Domain Name and the App ID, navigate to Settings>SDK (for Developers) in your agent dashboard and scroll down to "Initializing Helpshift" section. show me

Select your App from the dropdown and copy the three tokens to be passed when initializing Helpshift.

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

import com.helpshift.HelpshiftBridge;
import com.helpshift.exceptions.InstallException;

public class MyActivity extends Cocos2dxActivity {

    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        try {
          HelpshiftBridge.install(this,
                                  "YOUR_API_KEY",
                                  "YOUR_DOMAIN_NAME",
                                  "YOUR_APP_ID");
        } catch (InstallException e) {
          Log.e(TAG, "invalid install credentials : ", e);
        }
    }
}

Start using Helpshift

Helpshift is now integrated in your app. You should now use the support APIs to present FAQ or conversation screens inside your app.

Run your app, and try starting a test conversation using the showConversation API call. Then goto your Helpshift agent dashboard and reply to experience the in-app messaging.

Sample usage for FAQs and conversation APIs:

// Presenting FAQs to your customers
void GameSettingsScene::menuHelpCallback(CCObject* pSender)
{
    HelpshiftCocos2dx::showFAQs();
}

// Starting a conversation with your customers
void GameSettingsScene::menuConversationCallback(CCObject* pSender)
{
    HelpshiftCocos2dx::showConversation();
}

Next up

If you're using Proguard, take a look at additional configurations. If you're facing flickering issues with Cocos2d-x v2.x, follow these steps to fix it.

If you've successfully tested out an in-app conversation, it's time to dive into these advanced topics -

Helpshift APIs

Discover ways to do customer support via Helpshift.

Notifications

Configure Push and In-app notifications.

Tracking

Track events and user actions. Attach custom metadata to every conversation.

Reviews & Feedback

Asking for reviews and feedback.

Additional Configuration

  • If you are using Proguard, you will need to add the following to your project's proguard-project.txt file.

    -keep class android.support.** { *; }
    

    Helpshift Android SDK v2.8.2 and above is not pre-obfuscated with Proguard. To shrink & obfuscate the Helpshift SDK, we recommend you use this Proguard configuration in your project.

    Proguard is recommended for shrinking, optimizing, and obfuscating your code by removing unused code and renaming classes, fields, and methods with semantically obscured names. The result is a smaller sized APK file that is more difficult to reverse engineer. For more information refer Proguard Documentation

  • In your build.xml file, insert the following between the <target name="-post-compile"> tags. This will check the Helpshift xml files for the requisite resources and warn you if any of those resources are missing. If the "-post-compile" target is missing, wrap the below code snippet with <target name="-post-compile">...</target> tags.

    <path id="helpshift-classpath">
      <fileset dir="<path/to/Helpshift-SDK/libs>">
        <include name="Helpshift.jar"/>
      </fileset>
    </path>
    <java classname="com.helpshift.HSPostCompileCheck" failonerror="true">
      <classpath refid="helpshift-classpath"/>
      <arg value="<YOUR_APPLICATION_NAMESPACE>"/>
    </java>
    

Flickering issues with Cocos2d-x 2.x

Cocos2d-x v2.x has a bug which causes the screen to flicker when a dialog Activity is shown on top of it.

If you integrate Helpshift SDK for Cocos2d-x, you will see a flicker in your app when the Review Reminder dialog is shown.

To fix the bug, please apply the patch described on github.