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

Download SDK v1.9.0

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. To use the latest Cocos2dx plugin in your application, add a reference to the Helpshift Android SDK from your Android application's project.properties file. As of version 4.0.0, the Helpshift Android plugin sets the Android target to 23. To use this plugin, please set the target to android-23 in your application.

    android.library.reference.1=../helpshift-plugin-cocos2dx/v3.x/android/sdk/
    
  2. 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 app name is com.example.application, <provider> tag will now look like this:

    <provider
        android:name="com.helpshift.support.providers.HSPluginFileProvider"
        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>
    
  3. Copy the android/src/com/helpshift folder to the src/com/ folder of your Android project.

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

  5. Add HelpshiftCocos2dx.cpp to makefile (Android.mk), under the LOCAL_SRC_FILES rule. For example:

    LOCAL_SRC_FILES := hellocpp/main.cpp \
                  ../../Classes/AppDelegate.cpp \
                  ../../Classes/HelloWorldScene.cpp \
                  ../../Classes/HelpshiftCocos2dx.cpp
    
  6. Set the flag for manifestmerger.enabled to true in your project.properties file:

    manifestmerger.enabled=true
    
  7. Copy the hs__data file from the sdk/assets/ folder to the assets folder 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.