The Helpshift SDK is designed to provide your support team with valuable data about your end users to help resolve their inquiries. This data can include device properties (OS type and version and user location) user properties (how much they’ve spent, account creation date) and more. It can be used to route Issues to specialized Agents or Groups, prioritize select types of users (such as VIPs), and organize Issues for analytics tracking.
All of this data is captured by our SDK and can be represented in your Dashboard as metadata, Custom Data, Custom Issue Fields, and tags. This guide is designed to prepare you to work with your developer to implement these features to optimize your workflow.
For a quick introduction to Metadata, watch this video:
For more detailed steps and best practices, please see our Knowledge Base.
1. The Metadata Tab Within Issues
Metadata is listed on the ‘Metadata’ tab on the Issue details page of any in-app Issue. Custom Data, a subset of Metadata which we will define later in this section, is also listed here.
Metadata is information that is collected out-of-the-box from the device by our SDK when it is integrated into your app. This includes the user’s OS type, app version, device type, battery level, and more.
For email and web Issues, you will see a limited set of data pertaining to the user, including the email address and any options selected in your contact us form. To learn about populating your web metadata, please see How Do I Customize My Web Contact Us Form?
You will notice a section titled ‘Custom Data’ in your metadata tab for in-app Issues. Custom Data is data that is unique to your app that is not collected by default that your developers can configure our SDK to collect.
This data could include $ spent, User ID, install date, number of purchases, and anything else you’d like to know upon Issue creation. This section is also where the HS-Tags associated with this Issue are listed, which will be explained below.
2. Custom Issue Fields
Next to the Metadata tab in your Issue Details pane is the Custom Issue Fields tab. Custom Issue Fields allow you to classify Issues using fields made up of a label and a type. They can be configured to be automatically assigned to new Issues when metadata or Custom Data thresholds are met.
The label is where you provide the category of the field (tier, purchase date, country) and the type is where you define the kind of value which should be allowed to be entered into the field (a number, date, string, a drop-down, and more.)
Custom Issue Fields are recommended for categorizing Issues with a specific set of criteria to be prioritized, routed, and assigned within your workflow. They are useful for classifying Issues based on a number of categories, and presenting that data in a visible, easy-to-read place in the Issue details area.
The different field types available for use in Custom Issue Fields are as follows:
- Single line text – allows the Agent to enter a freeform text line (with a maximum 255 character length) within this field. This is good for data that will frequently be unique, such as a JIRA link.
- Multi line text – allows the Agent to enter several lines of freeform text within this field (with a maximum 100,000 character length). This is helpful for storing lengthy information like crash logs or mailing addresses.
- Number – restricts the field to number values, such as the tier level or purchase amount.
- Date – this field type will provide a calendar where the Agent can select a date, such as the user’s signup or purchase date.
- Drop-down – drop-downs allow you to limit the values the Agent can select to a set list. You could define your Issue types as a drop-down. Drop-downs are helpful for creating useful analytics metrics, since Agent’s can’t mistype the selection.
- Checkbox – this is best for yes/no or true/false values, such as ‘VIP’ or ‘paid’.
Custom Issue Fields can be configured in the backend by setting up your SDK to pass through metadata. To do so, please direct your developer to our developer documentation on passing through Custom Issue Fields for iOS and Android.
To learn more about Custom Issue Fields and see examples of how to use them, please see our guide to Custom Issue Fields.
HS-Tags are unique values that can be configured and paired with tags in the Dashboard to be automatically applied to new Issues when metadata or Custom Data thresholds are met, just like Custom Issue Fields.
Tags can be used to collect tag counts in Analytics, organize Issues within Smart Views, and serve as a quick way to reference Issue types from the Issues Feed. Custom Issue Fields are recommended for categorizing Issues to be prioritized, routed, and assigned within your workflow.
There are no predefined HS-Tags in the SDK; developer resources are required to add HS-Tags into your Dashboard. If you plan to use tags to categorize Issues, it’s essential that you meet with your developer to plan a set of HS-Tags that will best serve your support team’s needs.
To utilize the full functionality of HS-Tags, you must add corresponding tags in your Dashboard. Please note that your HS-Tags and tags in the Dashboard must be lowercase.
You can also create and apply tags in the Dashboard without having an equivalent HS-Tag in your SDK. This is useful for tags you may only need temporarily, such as bug reports.
You can manually apply tags to an Issue directly from the Issue details page via the ‘Add tags’ section.
A full list of all of your active tags added to the Dashboard can always be found via Settings > Active Tags.
As an example, you could have an HS-tag ‘paid’ for users who have spent money in your app. If a user is writing in who has spent more than a certain amount, say, $50 in your app, you can set it in the SDK so that the HS-Tag ‘paid’ will be automatically applied to the Issue.
To learn about more use cases for tags, please see How Do I Create And Use Tags?
4. Summary & Additional Resources
Here’s quick summary of each term as it’s defined above:
Metadata = Device information that is automatically collected by our SDK when it is integrated into your app
Custom Data = Data at the app level that your developers configure to pass through the SDK
Custom Issue Fields = Custom fields made up of a label and type that can be used to classify Issues which can be set up to be automatically added to Issues
HS-Tags = Custom values which must be set by your developer at the SDK level which can be automatically added to Issues when paired with an equivalent tag in the Dashboard
Now that you understand these terms, get started with each of them via the documentation below:
- Developer Implementation Guide
- How Do I Set Up Custom Data?
- Guide: Custom Issue Fields
- How Do I Create And Use Tags?
To set up additional features and learn more about Helpshift best practices, please review our Knowledge Base.