NativeScript Troubleshooting Guide

Common issues and solutions when integrating UXCam with NativeScript applications.

Quick Diagnostics Checklist

Before diving into specific issues:

NativeScript CLI is installed and up to date
UXCam plugin is latest version
Valid UXCam app key is configured
iOS deployment target is 12.0+ / Android minSdkVersion is 21+
App module is properly configured

Installation Issues

Plugin Installation Fails

Symptoms:

Error: Failed to install nativescript-uxcam

Solutions:

Update NativeScript CLI:

npm install -g nativescript
ns --version

Clear cache and reinstall:

ns clean
npm install nativescript-uxcam

For NativeScript 8+:

npm install @nicothin/nativescript-uxcam

Build Errors After Installation

iOS CocoaPods Error:

cd platforms/ios
pod install --repo-update

Android Gradle Error:

ns clean
ns build android

Runtime Issues

Sessions Not Appearing in Dashboard

Symptoms:

App runs normally
No sessions in UXCam dashboard

Debugging Steps:

Verify initialization:

// app.ts or main.ts
import { Application } from '@nativescript/core';
import * as NSUXCam from 'nativescript-uxcam';

Application.on(Application.launchEvent, () => {
    console.log('Initializing UXCam...');

    NSUXCam.optIntoVideoRecordings();
    NSUXCam.startWithKey('YOUR_APP_KEY');

    console.log('UXCam initialized');
});

Application.run({ moduleName: 'app-root' });

Check logs:

Android: adb logcat | grep UXCam
iOS: Xcode console

Common Solutions:

Wrong import:

// ✅ Correct import
import * as NSUXCam from 'nativescript-uxcam';

// ❌ Incorrect
import { UXCam } from 'nativescript-uxcam';

Late initialization:

// ❌ Too late - in a component
export class HomeComponent {
    ngOnInit() {
        NSUXCam.startWithKey(key); // May miss early screens
    }
}

// ✅ Correct - in app launch
Application.on(Application.launchEvent, () => {
    NSUXCam.startWithKey(key);
});

NSUXCam is Undefined

Symptoms:

TypeError: Cannot read property 'startWithKey' of undefined

Solutions:

Verify plugin installation:

ns plugin list
# Should show: nativescript-uxcam

Rebuild the app:

ns clean
ns build android
ns build ios

Screen Tagging Issues

Screens Not Tagged Correctly

Symptoms:

Generic screen names in dashboard
Missing screen transitions

Solution - Manual screen tagging:

Angular:

import { Component, OnInit } from '@angular/core';
import * as NSUXCam from 'nativescript-uxcam';

@Component({
    selector: 'home',
    templateUrl: './home.component.html'
})
export class HomeComponent implements OnInit {
    ngOnInit() {
        NSUXCam.tagScreenName('Home');
    }
}

Vue:

export default {
    mounted() {
        NSUXCam.tagScreenName('Home');
    }
}

Plain NativeScript:

export function onNavigatingTo(args) {
    NSUXCam.tagScreenName('Home');
}

With Router:

// Use router events for automatic tagging
import { RouterExtensions } from '@nativescript/angular';

constructor(private router: RouterExtensions) {
    this.router.router.events.subscribe(event => {
        if (event instanceof NavigationEnd) {
            const screenName = event.urlAfterRedirects.replace('/', '') || 'Home';
            NSUXCam.tagScreenName(screenName);
        }
    });
}

Occlusion Issues

Sensitive Data Visible

Solution - Occlude views:

import * as NSUXCam from 'nativescript-uxcam';
import { TextField } from '@nativescript/core';

// Get reference to sensitive field
const creditCardField = page.getViewById<TextField>('creditCard');

// Occlude it
NSUXCam.occludeSensitiveView(creditCardField);

Occlude entire screen:

// When showing sensitive screen
NSUXCam.occludeSensitiveScreen(true);

// When leaving
NSUXCam.occludeSensitiveScreen(false);

Platform-Specific Issues

iOS: Recording Not Starting

Solution:

// Required for iOS
NSUXCam.optIntoVideoRecordings();
NSUXCam.startWithKey('YOUR_APP_KEY');

iOS: Build Fails with Pod Errors

cd platforms/ios
pod deintegrate
pod install

Android: ProGuard Issues

Add to App_Resources/Android/proguard-rules.pro:

-keep class com.uxcam.** { *; }
-dontwarn com.uxcam.**

TypeScript Type Issues

Missing Type Definitions

Solution - Add declaration file references.d.ts:

/// <reference path="./node_modules/nativescript-uxcam/index.d.ts" />

Or use any type:

const NSUXCam: any = require('nativescript-uxcam');

Debug Information Collection

When contacting support, include:

Environment:

ns --version
ns doctor
node --version
npm --version

Plugin version:

npm list nativescript-uxcam

Device logs:

Android: adb logcat | grep UXCam
iOS: Xcode console

Configuration:

package.json
Initialization code

Contact Support

Email: [email protected]
Documentation: NativeScript Integration Guide
Changelog: Version History