pikd_flutter_experience

pikd_flutter_experience is the turnkey PIKD flow for Flutter. It opens a full-screen PIKD experience containing Challenges, Explore, AR Collect, Leaderboard, and Profile/Inventory. Your app supplies authenticated user identity and tenant configuration; PIKD owns its internal screens, navigation, AR session, asset placement, collection, and return flow. The bottom navigation is ordered Explore → Challenges → AR → Leaderboard → Profile; AR is the raised, centred camera action.

Release candidate: 0.8.0-beta.12.

Install

dependencies:
  pikd_flutter_experience: ^0.8.0-beta.12

Run flutter pub get with Flutter 3.44 or later.

Host setup

The SDK owns the PIKD flow, but your host app still owns platform credentials and permission declarations:

  • A Google Maps key: Android manifest com.google.android.geo.API_KEY, plus GMSServices.provideAPIKey(...) in iOS AppDelegate.
  • Android minSdk 24 or higher, google() and mavenCentral() repositories, and camera/coarse/fine-location permissions.
  • iOS deployment target 15 or higher, plus camera and when-in-use location usage descriptions.
  • A physical device for AR.

PIKD works with FlutterActivity and FlutterFragmentActivity. If your app uses local_auth or another FragmentActivity-based plugin, retain your existing FlutterFragmentActivity; do not replace it with a PIKD-specific activity.

On Android, the experience checks Google Play Services for AR before opening the camera and displays Google's standard install/update prompt when necessary. If AR is unavailable or unsupported, it keeps the rest of PIKD available and offers a return to the map. No host-side ARCore preflight code is required.

Launch PIKD

Build this configuration after your host user has authenticated. userRef must be a stable, opaque string for that user. An integer client ID is valid after calling toString().

import 'package:pikd_flutter_experience/pikd_flutter_experience.dart';

Future<void> openPikd(BuildContext context, int clientId) {
  return PikdFlutterExperience.open(
    context,
    configuration: PikdFlutterExperienceConfiguration(
      baseUrl: 'https://api.example.pikd.app/api/sdk/v1',
      sdkKey: issuedPikdSdkKey,
      userRef: clientId.toString(),
      // The host application's currently selected language.
      locale: PikdLocale.russian,
      // Tenant-supported language for API content such as challenge, drop,
      // and collected-item titles.
      contentLanguageRef: 'ru',
      theme: magnumTheme,
    ),
  );
}

The returned future completes after the user closes PIKD. There is no global initialization: pass the current user's configuration each time you open it.

locale controls PIKD's own interface and supports PikdLocale.russian and PikdLocale.kazakh. contentLanguageRef is separate because content support is tenant-specific: set it to a language PIKD has enabled for the tenant rather than assuming that every UI language has matching API content.

Theme and typography

Pass a PikdTheme once and it applies throughout every PIKD screen, sheet, detail route, and AR overlay. The package bundles Manrope as an OFL-licensed fallback. It does not redistribute a host's commercial font.

If your app legally bundles Cera Pro under the family name Cera Pro, reuse the standard PIKD type scale with it:

final magnumTheme = PikdTheme.pikdDefault().copyWith(
  colors: PikdColors.dark.copyWith(
    primary: const Color(0xFFF50F64),
    onPrimary: const Color(0xFFFFFFFF),
    activeAccent: const Color(0xFFFA91AF),
    surfaceBrand: const Color(0xFFFA91AF),
    success: const Color(0xFF00C387),
    warning: const Color(0xFFFF8200),
    error: const Color(0xFFF9423A),
    info: const Color(0xFF59CBE8),
  ),
  typography: PikdTypography.poppins.withFontFamily('Cera Pro'),
  brandName: 'Magnum',
);

Use Manrope instead if Cera Pro is not bundled by your app. Do not copy a commercial font into the PIKD package without redistribution rights.

Current turnkey scope

The turnkey flow owns Challenges (list, detail, comments, and challenge-scoped leaderboard), Explore, AR/Collect, Leaderboard, and Profile/Inventory. pikd_flutter_api, pikd_flutter_ui, and pikd_flutter_ar remain available for applications that need individual PIKD primitives. Feed is not part of this encapsulated flow.

Fixed-campaign presentation

The generic experience remains multi-campaign by default. For a tenant with one active campaign, pass campaign to preselect it in Explore, remove the challenge-picker row, open Mechanics directly to its detail page, use a direct My Collections destination, and apply tenant-safe leaderboard presentation:

campaign: PikdCampaignExperienceConfiguration(
  challengeId: activeCampaignId,
  title: approvedCampaignTitleForCurrentLocale,
  hideLeaderboardAvatars: true,
),

pikd_flutter_magnum_experience resolves Magnum's single active challenge at launch and creates this configuration internally. Use the generic package directly when your app needs the multi-campaign flow or lower-level composition.

License

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

Libraries

pikd_flutter_experience