From Heap Core SDK + Contentsquare SDK to CSQ SDK

Heap Core SDK

+

Contentsquare SDK

→

CSQ SDK

The latest version of our SDK provides a unified set of APIs for Product Analytics, Experience Analytics, and Experience Monitoring, eliminating redundant APIs that perform the same actions.

Upgrading to the latest version ensures you benefit from all our newest features and product enhancements.

Increment the Contentsquare SDK in pubspec.yaml to the latest version.

dependencies:
  heap_flutter_bridge: ^0.4.0
  heap_flutter_autocapture: ^0.6.0
  contentsquare: ^3.19.1
  contentsquare: ^4.0.0

Sync your dependencies by running flutter pub get.

Replace the Contentsquare SDK import with a CSQ SDK import.

import 'package:heap_flutter_bridge/heap_flutter_bridge.dart';
import 'package:heap_flutter_autocapture/heap_flutter_autocapture.dart';
import 'package:contentsquare/contentsquare.dart';
import 'package:contentsquare/csq.dart';

1. Optional: If you were using ContentsquareRoot widget - remove it from your widget tree.

   void main() {
     runApp(const MyApp());
   }
   
   class MyApp extends StatelessWidget {
     @override
     Widget build(BuildContext context) {
       return ContentsquareRoot(
         child: MaterialApp(
       return MaterialApp(
         title: 'My Flutter App',
         home: Home()
         ),
       );
     }
   }

2. Delete Heap().startRecording() and migrate options to CSQ().configureProductAnalytics().

   import 'package:contentsquare/csq.dart';
   
   void main() async {
     await Heap().startRecording('YOUR_ENVIRONMENT_ID', {
       // your previous options
     });
     await CSQ().configureProductAnalytics(
       environmentId: 'YOUR_ENVIRONMENT_ID',
       options: ProductAnalyticsOptions(
         // Migrate options here
       ),
     );
   }

3. Start the CSQ SDK manually.

   Add the CSQ().start() call after the configuration (and remove Contentsquare().start() if you had it before):

   import 'package:contentsquare/csq.dart';
   
   void main() async {
     await CSQ().configureProductAnalytics(
       environmentId: 'YOUR_ENVIRONMENT_ID',
       options: ProductAnalyticsOptions(
         // Migrate options here
       ),
     );
   
     await Contentsquare().start();
     await CSQ().start();
   }

4. Remove HeapAutocapture registration:

   await HeapAutocapture.register();

5. Update pageview autocapture setup

   import 'package:contentsquare/csq.dart';
   
   await HeapAutocapture.register();
   
   MaterialApp(
     navigatorObservers: [
       HeapNavigatorObserver(),
       CSQNavigatorObserver(),
     ],
     home: MyHomePage(),
   )

6. Recommended In order to enable automatic capture of user interactions, add the option enableInteractionsAutocapture: true to your ProductAnalyticsOptions configuration:

   import 'package:contentsquare/csq.dart';
   
   void main() async {
     await CSQ().configureProductAnalytics(
       environmentId: 'YOUR_ENVIRONMENT_ID',
       options: ProductAnalyticsOptions(
         enableInteractionsAutocapture: true,
       ),
     );
     await CSQ().start();
   }

7. (Optional) If you were relying on the Contentsquare SDK autostart, remove the CSDisableAutostart property and calls to Contentsquare.start().

   • Swift
   • Objective-C

   <key>CSDisableAutostart</key>
   <true/>

   Contentsquare.start()

8. (Optional) If you have chosen to deactivate the autostart of the Contentsquare SDK, you can now remove the entry in the manifest, as the CSQ SDK doesn’t have an autostart.

   <application>
     ...
       <meta-data
         android:name="com.contentsquare.android.autostart"
         android:value="false"
       />
     ...
   </application>

9. Remove Heap Android dependencies

   dependencies {
     implementation("io.heap.core:heap-android-core:+")
     implementation("io.heap.contentsquare.csbridge:contentsquare-bridge:+")
   }

10. Remove Heap iOS dependencies:

    • Swift Package Manager
    • CocoaPods
    1. In Xcode, navigate to your project settings.
    2. Select your app target, then go to the Frameworks, Libraries, and Embedded Content section.
    3. Find HeapContentsquareIntegrationSDK in the list and click the - button to remove it.
    4. Go to File → Packages → Resolve Package Versions to update your package dependencies.

11. Remove Initializing Integration:

    • Kotlin
    • Swift

    HeapContentsquareIntegration.bind(
      applicationContext,
      sendHeapPageviewsToContentsquare = false,
      sendContentsquareScreenviewsToHeap = true
    )

Implement the optIn() API to forward user consent to the SDK and generate a user ID.

The CSQ SDK treats users as opted-out by default.

It can be done immediately after start is called:

void main() async {
  // ...
  await CSQ().start();
  await CSQ().optIn();
  // ...
}

Alternatively, you can call optIn() in response to a user action, such as tapping an “I agree” button:

class UserConsentScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('User Consent'),
      ),
      body: Center(
        child: ElevatedButton(
          onPressed: () async {
            await CSQ().optIn();
          },
          child: Text('Agree with Terms and Conditions'),
        ),
      ),
    );
  }
}

Search and replace all legacy SDK API calls in your app to the latest CSQ APIs using the following mappings. Updating your API calls ensures continued functionality without disruption.

In most cases, this process consists in updating the namespace and method names, with no changes to parameters.

Contentsquare().start()
CSQ().start()

For more information on SDK methods, see the SDK API reference.

GDPR / Identification

Contentsquare().forgetMe()

You can use CSQ().optOut() instead to forget user id and stop tracking. If needed call CSQ().optIn() when you want to resume tracking.

Property tracking

CSInApp (iOS only)

Interoperability

Event tracking

Error tracking

Personal Data Handling and Masking

SDK initialization and manipulation

GDPR / Identification

Logging

Property tracking

Event tracking

Personal Data Handling and Masking

SDK initialization and manipulation