Approov Service for Flutter Dio HTTP/2 #

Approov support for Flutter apps that use the Dio client with HTTP/2 transport via dio_http2_adapter.

In order to use this package, you will need a trial or paid Approov account.

ADDING APPROOV SERVICE DEPENDENCY #

To add the Approov service integration to your Flutter project, add approov_service_flutter_dio_http2 to your pubspec.yaml dependencies:

dependencies:
  flutter:
    sdk: flutter
  dio: ^5.9.0
  approov_service_flutter_dio_http2:
    path: /path/to/approov-service-flutter-dio-http2  # Or use a git/pub reference

Then run:

flutter pub get

PLATFORM CONFIGURATION #

Android #

The following app permissions need to be declared in your AndroidManifest.xml (usually under android/app/src/main/AndroidManifest.xml) to allow Approov to function:

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.INTERNET" />

Note that the minimum Android SDK version you can use with this package is 23 (Android 6.0). If targeting Android 11 (API level 30) or above, please read the Android targeting instructions.

iOS #

No additional permissions are required on iOS. Ensure your deployment target is iOS 12.0 or above.

INITIALIZING APPROOV SERVICE #

In order to use the ApproovService you must initialize it before sending any network requests, typically in your app's main() entrypoint:

import 'package:approov_service_flutter_dio_http2/approov_service_flutter_dio_http2.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  // Initialize Approov service with your config string
  try {
    await ApproovService.initialize("<enter-your-config-string-here>");
  } catch (e) {
    print("Approov initialization failed: $e");
  }

  runApp(const MyApp());
}

The <enter-your-config-string-here> configuration string configures your Approov account access. This is provided in your Approov onboarding email.

USING APPROOV SERVICE #

You can easily enable Approov protection for a Dio instance using the ApproovDioHttp2.install() convenience helper:

import 'package:approov_service_flutter_dio_http2/approov_service_flutter_dio_http2.dart';
import 'package:dio/dio.dart';

final dio = Dio();

// Install the Approov HTTP/2 adapter on the Dio client
ApproovDioHttp2.install(
  dio,
  fallbackPolicy: ApproovHttp2FallbackPolicy.protectedHttp1,
);

// Any requests sent via this dio instance are now protected by Approov
final response = await dio.get("https://api.example.com/v1/data");
print("Status: ${response.statusCode}");

This updates dio.httpClientAdapter with an ApproovDioHttp2Adapter instance. The adapter handles certificate pinning validation, token injection, message signing, and secret substitutions automatically at the transport boundary before sending HTTP/2 frames.

CUSTOM OPTIONS & ADAPTER CONFIGURATION #

You can customize the adapter behavior by passing explicit parameters to ApproovDioHttp2.install() or the ApproovDioHttp2Adapter constructor:

ApproovDioHttp2.install(
  dio,
  fallbackPolicy: ApproovHttp2FallbackPolicy.protectedHttp1,
  redirectPolicy: ApproovRedirectPolicy.manual,
  bodySigningPolicy: ApproovBodySigningPolicy.bufferUpToLimit,
  maxBodyBytesForSigning: 1024 * 1024,
  idleTimeout: Duration(seconds: 15),
  handshakeTimeout: Duration(seconds: 15),
);

• fallbackPolicy: Determines the behavior if ALPN fails to negotiate HTTP/2. protectedHttp1 (default) falls back to a pinned HTTP/1.1 path. failIfHttp2Unavailable aborts the request.
• redirectPolicy: manual (default) handles redirects at the adapter level so that Approov processing and pin validation are re-applied to each redirect target domain.
• bodySigningPolicy: Determines how streaming request bodies are handled for message signing. Options are bufferUpToLimit (default), skipDigestForStreamingBodies, and failIfBodyDigestRequiredAndStreaming.
• maxBodyBytesForSigning: Maximum bytes buffered for digest computation when signing request bodies.

CHECKING IT WORKS #

Initially, you won't have protected API domains set up in your Approov account, so the adapter will not modify requests. However, it will contact the Approov cloud service to verify the app's integrity. You should see logging from Approov saying UNKNOWN_URL.

You can verify that your app is successfully communicating with the Approov service by accessing the Live Metrics Graphs link provided in your onboarding email. Within a minute of running the app, attestation requests should register on the charts.

NEXT STEPS #

To secure your API endpoints and protect app secrets, refer to these guides:

• API Protection: Ensure your backend API parses and validates the issued Approov JWT token. An Approov Token is a short-lived, cryptographically signed JWT.
• Secrets Protection: Protect API keys and other app secrets so they no longer need to be hardcoded in your source code. These secrets are only made available to genuine, attested app instances at runtime.

• See REFERENCE.md for the detailed API reference.
• See USAGE.md for usage patterns and examples (Token Binding, message signing, exclusions, substitutions, etc.).
• See MIGRATION.md for migration paths from standard Dart HttpClient wrappers.
• See CHANGELOG.md for version changes.