PIKD SDK API for Dart #

Typed Dart client for the PIKD /sdk/v1 API. It provides authentication, collectibles, challenges, profiles, collections, leaderboards, feeds, and AR session telemetry for applications that compose individual PIKD capabilities.

Release candidate: pikd_flutter_api version 0.8.0-beta.14.

Requirements #

• Dart 3.3 or later
• A PIKD SDK key issued for your tenant
• A separate written SDK agreement with ELEOS WORLD LTD

Installation #

After the package is published, add it from pub.flutter-io.cn:

dependencies:
  pikd_flutter_api: ^0.8.0-beta.14

Then resolve dependencies:

dart pub get

Configure the client #

Do not hard-code production SDK keys in source control. Inject them through your environment or deployment system and add the key to an ApiClient:

import 'package:pikd_flutter_api/api.dart';

final client = ApiClient(basePath: 'https://api.pikd.app/sdk/v1')
  ..addDefaultHeader('x-pikd-sdk-key', sdkKey);

final collectiblesApi = CollectiblesApi(client);

Tier 1 and higher integrations should also pass the opaque PIKD user reference required by the selected endpoint. Do not send personally identifiable user data as the user reference.

Find nearby collectibles #

final collectibles = await collectiblesApi.getNearbyCollectibles(
      latitude,
      longitude,
      radiusM: 250,
      languageRef: selectedContentLanguageRef,
      xPikdUser: pikdUserReference,
    ) ??
    const <Collectible>[];

final collectedItems = await ProfileApi(client).getInventory(
  pikdUserReference,
  languageRef: selectedContentLanguageRef,
) ??
    const <InventoryItem>[];

for (final collectible in collectibles) {
  print('${collectible.id}: ${collectible.title}');
}

Collect an item #

Anonymous Tier-0 integrations can omit the collection request body:

final result = await collectiblesApi.collectCollectible(collectibleId);
print(result?.status);

Identified integrations pass their opaque host reference. Supply languageRef when the host supports localized customer-facing validation errors:

final result = await collectiblesApi.collectCollectible(
  collectibleId,
  collectRequestBody: CollectRequestBody(
    userRef: hostUserReference,
    languageRef: selectedContentLanguageRef,
  ),
);

languageRef is optional. Magnum sends its canonical ru or kk content language so the service can return localized validation copy. Existing integrations using the deprecated userRefBody parameter remain source compatible, but new integrations should use CollectRequestBody.

API failures throw ApiException. Handle them at the boundary where your app maps network errors to user-visible states.

Authentication #

The package supports the authentication schemes generated from the PIKD OpenAPI contract. Most SDK endpoints use the tenant key in the x-pikd-sdk-key header. Tier 1 integrations can exchange a signed host assertion through AuthApi for an opaque PIKD user identifier.

Available APIs #

• AuthApi
• ChallengesApi
• CollectiblesApi
• FeedApi
• LeaderboardApi
• ProfileApi
• TelemetryApi

Generated endpoint and model references are included under doc/. A runnable nearby-collectibles example is available in example/pikd_flutter_api_example.dart.

Regeneration #

The client implementation is generated from the versioned PIKD OpenAPI contract. Public metadata, this README, the changelog, the license, and examples are intentionally protected by .openapi-generator-ignore and must be reviewed separately from generated source changes.

License #

This package is proprietary software. Use requires a written SDK agreement with ELEOS WORLD LTD. See LICENSE and the PIKD SDK license page.