report static method

EventHandler? report({
  1. required int prepareId,
  2. required int categId,
  3. String description = '',
  4. Uint8List? snapshot,
  5. ImageFileFormat? format,
  6. ParameterList? params,
  7. void onComplete(
    1. GemError error
    )?,
})

Submits a prepared social event report to the community.

Uploads a previously prepared report (via prepareReporting or prepareReportingCoords) with the specified category, optional description, image snapshot, and custom parameters. The report becomes visible to all users with social overlay enabled and displays for a limited duration before automatic removal.

Reports must be prepared before submission to validate location accuracy and rate limiting. The preparation step returns a prepareId that must be used within a short time window before expiration.

Parameters

  • prepareId: Prepared operation ID returned by prepareReporting or prepareReportingCoords. Must be used before expiration (typically within a few minutes).
  • categId: Report category or subcategory ID. Must match a valid social report category. See SocialReportsOverlayInfo.getSocialReportsCategories for available IDs.
  • description: Optional text description providing additional context about the reported event (default: empty string).
  • snapshot: Optional image data (Uint8List) for the report. Must be provided together with format. If provided without format, returns GemError.invalidInput immediately.
  • format: Image format for snapshot (e.g., ImageFileFormat.png, ImageFileFormat.jpeg). Required if snapshot is provided.
  • params: Optional custom parameters following the structure from SocialReportsOverlayCategory.parameters.find(PredefinedOverlayGenericParametersIds.keyVals). Use PredefinedReportParameterKeys for standard parameter keys.
  • onComplete: Callback invoked when the operation completes or fails. Called with:
    • GemError.success when report is successfully submitted and visible.
    • GemError.invalidInput if categId is invalid, params are ill-formed, snapshot is invalid, or snapshot/format mismatch.
    • GemError.suspended if user has exceeded report rate limit (too many reports in short time period).
    • GemError.expired if prepareId not found or too old (preparation expired).
    • GemError.notFound if no high-accuracy position data available to complete the report (position lost after preparation).

Returns

  • EventHandler if operation was successfully initiated (use with cancel).
  • null if operation could not be started (e.g., snapshot/format mismatch detected immediately).

Example

SocialOverlay.report(
  prepareId: prepareId,
  categId: categId,
  onComplete: (error) {
    if (error == GemError.success) {
      print('Report submitted successfully');
    } else {
      print('Report failed: $error');
    }
  },
);

See also:

Implementation

static EventHandler? report({
  required final int prepareId,
  required final int categId,
  final String description = '',
  final Uint8List? snapshot,
  final ImageFileFormat? format,
  final ParameterList? params,
  final void Function(GemError error)? onComplete,
}) {
  if ((snapshot == null) != (format == null)) {
    onComplete?.call(GemError.invalidInput);
    return null;
  }

  dynamic gemImage;
  if (snapshot != null) {
    gemImage = GemKitPlatform.instance.createGemImage(snapshot, format!.id);
  }
  try {
    final EventDrivenProgressListener progListener =
        EventDrivenProgressListener();
    GemKitPlatform.instance.registerEventHandler(
      progListener.id,
      progListener,
    );

    progListener.registerOnCompleteWithData((final int err, _, _) {
      GemKitPlatform.instance.unregisterEventHandler(progListener.id);
      onComplete?.call(GemErrorExtension.fromCode(err));
    });

    final OperationResult result = staticMethod(
      'SocialOverlay',
      'report',
      args: <String, dynamic>{
        'prepareId': prepareId,
        'categId': categId,
        'description': description,
        'snapshot': gemImage ?? 0,
        'params': params != null ? params.pointerId : 0,
        'listener': progListener.id,
      },
    );
    final int id = result['result'];
    final GemError error = GemErrorExtension.fromCode(id);

    if (error != GemError.scheduled) {
      GemKitPlatform.instance.unregisterEventHandler(progListener.id);
      onComplete?.call(error);
      return null;
    }

    return progListener;
  } finally {
    if (gemImage != null) {
      GemKitPlatform.instance.deleteCPointer(gemImage);
    }
  }
}