Hark · Flutter SDK
Planned Flutter SDK

Collect Hark Responses from Flutter with one small SDK.

Use HarkClient to load a Hark, collect text, audio, video, attachments, and field values, then submit everything with one clean API.

Overview

The Flutter SDK gives app developers a simple way to collect Hark Responses from a native app.

Developers initialize the SDK with a publishable integrationId, load a Hark, render the fields returned by the SDK, optionally upload media, and submit a Hark Response. Hark handles transport, media upload preparation, validation mapping, and response creation.

Installation

The package name and version below are placeholders until the SDK is published.

pubspec.yaml 
dependencies:
  hark_flutter: ^0.1.0

Apps can use their preferred camera, audio recorder, image picker, and file picker packages. The Hark SDK only needs a file-like object or bytes when uploading media.

Quick start

Initialize the client, load a Hark, upload media if needed, and submit a Hark Response.

Video Hark Response example 
import 'package:hark_flutter/hark_flutter.dart';

final hark = HarkClient(
  integrationId: 'hark_pub_abc123',
);

Future<void> submitVideoResponse(HarkFile videoFile) async {
  final reportABug = await hark.getHark('report-a-bug');

  final recording = await hark.uploadMedia(
    file: videoFile,
    purpose: UploadPurpose.recording,
    onProgress: (progress) {
      print('Upload: ${progress.percent}%');
    },
  );

  final response = await hark.submit(
    harkId: reportABug.id,
    type: HarkResponseType.video,
    recording: recording,
    contact: const HarkContact(
      name: 'Jane Customer',
      email: 'jane@example.com',
    ),
    fields: const {
      'order_number': '12345',
      'experience_rating': '5',
    },
  );

  print('Hark Response received: ${response.id}');
}

SDK steps

A typical Flutter integration has five steps.

Initialize

Create a HarkClient with a publishable integrationId. No secret key is shipped in the app.

Load a Hark

Fetch the public configuration needed to render a feedback screen: title, description, allowed response types, brand hints, and fields.

Collect input

Render native controls from SDK-level field types and collect contact details, text, media, and field values.

Upload media

Pass files or bytes to uploadMedia. The SDK manages the upload session and returns an opaque HarkUpload.

Submit

Call submit with the Hark, response type, contact, field values, and any uploads. Hark returns a compact receipt.

Configuration

A Hark contains what a native app needs to render the Hark experience.

Loading a Hark 
final reportABug = await hark.getHark('report-a-bug');

print(reportABug.title);
print(reportABug.description);
print(reportABug.allowedResponseTypes);
print(reportABug.brand.primaryColor);
print(reportABug.fields);

Hark shape

Property Type Purpose
id String Opaque public identifier for the Hark.
title String Primary heading to show in the native UI.
description String? Optional helper copy for the Hark.
brand HarkBrand Logo and simple color hints for native presentation.
allowedResponseTypes List<HarkResponseType> Response modes the app offers.
fields List<HarkField> SDK-level field definitions to render.

Rendering fields

The SDK normalizes Hark field configuration into a small set of field types that map cleanly to native Flutter widgets.

text textarea number select multiselect rating nps date image
SDK field Suggested Flutter widget Value to submit
text / textarea TextField User-entered string.
number TextField with numeric keyboard. String or number accepted by SDK.
select DropdownButton or custom picker. Selected option id.
multiselect Checkbox list or chips. List of selected option ids.
rating / nps Stars, buttons, segmented controls, or slider. Selected numeric value.
image Photo picker or camera capture. HarkUpload returned by the SDK.
Field model 
class HarkField {
  final String id;
  final String label;
  final HarkFieldType type;
  final bool required;
  final String? helpText;
  final List<HarkFieldOption> options;
}
!
Advanced rules: validation and conditional behavior arrive as public properties like required, options, and visibleWhen.

Media uploads

Apps hand the SDK a media file, image, or byte stream. The SDK handles upload preparation, progress reporting, retries where safe, and returns an opaque upload object.

Upload media 
final recording = await hark.uploadMedia(
  file: videoFile,
  purpose: UploadPurpose.recording,
  contentType: 'video/mp4',
  onProgress: (progress) {
    setState(() => uploadPercent = progress.percent);
  },
);

Upload purposes

Purpose Use case
recording Primary audio, video, or screen capture.
thumbnail Optional preview image for a video response.
attachment Supplemental files provided by the customer.
fieldImage Image value for a field in the Hark.

Submit a Hark Response

The SDK supports text-only, audio, video, and screen-based feedback through one submit method.

Text-only Hark Response

Submit a text response 
final response = await hark.submit(
  harkId: 'feedback',
  type: HarkResponseType.text,
  message: 'Love the new feature. Please add dark mode next.',
  contact: const HarkContact(
    email: 'jane@example.com',
  ),
);

Video Hark Response with fields

Submit a video response 
final response = await hark.submit(
  harkId: 'report-a-bug',
  type: HarkResponseType.video,
  recording: recording,
  thumbnail: thumbnail,
  contact: const HarkContact(
    name: 'Jane Customer',
    email: 'jane@example.com',
    preferredMethod: HarkContactMethod.email,
  ),
  fields: {
    'order_number': '12345',
    'experience_rating': 5,
    'bug_summary': 'The app freezes after checkout.',
  },
  attachments: [screenshotUpload],
);

Hark Response receipt

Property Type Purpose
id String Opaque receipt identifier for support and debugging.
status HarkResponseStatus Compact public status, initially received.
createdAt DateTime Timestamp when Hark accepted the response.

Error handling

The SDK translates failures into a small set of typed exceptions that Flutter apps can handle predictably.

Typed exceptions 
try {
  await hark.submit(
    harkId: 'report-a-bug',
    type: HarkResponseType.text,
    message: message,
    contact: contact,
    fields: fieldValues,
  );
} on HarkValidationException catch (error) {
  showInlineError(error.message);
} on HarkUploadException {
  showRetryUploadPrompt();
} on HarkRateLimitException {
  showTemporaryUnavailableMessage();
} on HarkNetworkException {
  showNetworkErrorMessage();
}
Exception When it happens Recommended app behavior
HarkValidationException Missing or invalid user-provided values. Show the message and let the user correct the form.
HarkUploadException Media upload could not complete. Let the user retry the upload.
HarkRateLimitException Too many requests or Hark Responses. Ask the user to wait before trying again.
HarkNetworkException Connectivity or timeout issue. Show a generic network error and allow retry.

SDK API

These are the core symbols in the planned Flutter package.

Symbol Kind Responsibility
HarkClient Class Entry point for configuration, uploads, Hark Responses, and events.
getHark Method Loads one public Hark by id.
uploadMedia Method Uploads media or attachments and returns HarkUpload.
submit Method Creates a Hark Response from public SDK objects.
trackImpression Method Optionally records that a user opened a Hark.
Hark Model Public configuration for a Hark.
HarkField Model SDK-level input definition for native rendering.
HarkUpload Model Opaque uploaded asset reference.
HarkResponse Model Compact receipt returned after Hark accepts a response.

Optional impression tracking

Track a Hark open 
await hark.trackImpression(
  harkId: 'report-a-bug',
  context: const HarkEventContext(
    screen: 'settings/help/report-bug',
  ),
);