[](https://badge.fury.io/js/avo-inspector)
npm install avo-inspector
This is a quick start guide.
For more information about Inspector project please read Avo documentation.
> If you are using SSR or web workers switch to this library build
> If you are looking for React Native library please switch to this branch and use react-native-avo-inspector npm package.
The library is distributed with npm
```
npm i avo-inspector
or
``
yarn add avo-inspector
Obtain the API key at Avo.app
`javascript
import * as Inspector from "avo-inspector";
let inspector = new Inspector.AvoInspector({
apiKey: "your api key",
env: Inspector.AvoInspectorEnv.Dev,
version: "1.0.0",
appName: "My app",
suffix: "unique-string" // optional, if you have more than 1 instance of Avo Inspector in same project
});
`
Logs are enabled by default in the dev mode and disabled in prod mode.
`javascript`
inspector.enableLogging(true);
The setup is lightweight and is covered in this guide.
Every event sent with Avo Function after this integration will automatically be sent to Inspector.
Whenever you send tracking event call one of the following methods:
Read more in the Avo documentation
This method gets actual tracking event parameters, extracts schema automatically and sends it to the Inspector backend.
It is the easiest way to use the library, just call this method at the same place you call your analytics tools' track methods with the same parameters.
`javascript`
inspector.trackSchemaFromEvent("Event name", {
"String Prop": "Prop Value",
"Float Prop": 1.0,
"Boolean Prop": true,
});
If you prefer to extract data schema manually you would use this method.
`javascript`
inspector.trackSchema("Event name", [
{ propertyName: "String prop", propertyType: "string" },
{ propertyName: "Float prop", propertyType: "float" },
{ propertyName: "Boolean prop", propertyType: "boolean" },
]);
`javascript`
let schema = inspector.extractSchema({
"String Prop": "Prop Value",
"Float Prop": 1.0,
"Boolean Prop": true,
});
You can experiment with this method to see how more complex schemas look, for example with nested lists and objects.
Inspector supports encrypting property values in development and staging environments. This allows you to see actual property values in Avo's debugging tools without exposing sensitive data, since only you hold the private decryption key.
- Uses ECC (Elliptic Curve Cryptography) with prime256v1 (NIST P-256) for strong security, standard for Web Crypto API
- Zero-knowledge architecture: Avo never has access to your private key
- No message size limitations
- Only active in dev/staging environments (production is unaffected)
Use the built-in CLI tool to generate a key pair:
`bash`
npx avo-inspector generate-keys
This will output:
- Public key: Pass this to the SDK to enable encryption
- Private key: Save this externally (you'll use it to decrypt values in Avo's dashboard)
Pass the publicEncryptionKey parameter when initializing Inspector:
`javascript
import * as Inspector from "avo-inspector";
let inspector = new Inspector.AvoInspector({
apiKey: "your api key",
env: Inspector.AvoInspectorEnv.Dev,
version: "1.0.0",
publicEncryptionKey: "your-public-key-hex-string" // Enable encryption
});
`
Note: The public key is not a secret - you can hardcode it, store it in .env, or configure it however you prefer. The SDK only uses the public key to encrypt values before sending them to Avo.
Private key: Save it securely (password manager, secure notes). Never expose it to the SDK. You only need it when viewing encrypted values in Avo's dashboard.
When encryption is enabled:
- Property values are encrypted before being sent to Avo
- You can decrypt them in Avo's dashboard using your private key
- Works with all data types: strings, numbers, booleans, objects, arrays, null
- Handles large payloads (1KB+) without issues
When initialized with a publicEncryptionKey in dev or staging environments, Inspector performs client-side validation of your events against your Avo Tracking Plan.
1. Event Spec Fetching: When you track an event, Inspector fetches the event specification from Avo's backend (results are cached for performance).
2. Event Matching: Inspector matches your event to the closest event in your tracking plan, considering event names, mapped names, and variant-specific properties.
3. Property Validation: Your event properties are validated against the spec rules:
- Required properties are present
- Property types match (string, int, float, boolean, object, list)
- Numeric values are within min/max bounds
- String values match regex patterns
- Enum values are in the allowed list
- Pinned values match exactly (variant-specific fixed values)
- No unexpected properties are sent
4. Immediate Reporting: Validated events bypass batching and are sent immediately to Inspector, ensuring you get real-time feedback.
If logging is enabled, validation errors are logged to the console:
`javascript
inspector.enableLogging(true);
// If "User Signed Up" requires an "email" property:
inspector.trackSchemaFromEvent("User Signed Up", { name: "John" });
// Console: [Avo Inspector] Validation errors for event "User Signed Up": [{ code: "RequiredMissing", propertyName: "email" }]
`
Note: Client-side validation only works with trackSchemaFromEvent, which has access to actual property values needed for validation.
The trackSchema method only sends pre-extracted schemas and does not perform client-side validation - it goes through the normal batching flow.
`javascript
// ✅ Validates against tracking plan (when publicEncryptionKey is provided)
inspector.trackSchemaFromEvent("Event Name", { prop: "value" });
// ❌ Does NOT validate - only sends schema, uses batching
inspector.trackSchema("Event Name", [{ propertyName: "prop", propertyType: "string" }]);
`
trackSchemaFromEvent returns a Promise that resolves with the validated properties. You can use this in two ways:
Call without await for non-blocking behavior. The event is tracked asynchronously and validation happens in the background:
`javascript`
// Non-blocking - validation runs in background
inspector.trackSchemaFromEvent("Event Name", { prop: "value" });
If you need to access validation results (e.g., for testing or debugging), you can await the call:
`javascript
// Blocking - wait for validation to complete
const validatedProperties = await inspector.trackSchemaFromEvent("Event Name", {
email: "user@example.com",
age: 25
});
// Each property includes validation results:
// {
// propertyName: "email",
// propertyType: "string",
// failedEventIds: [], // Event IDs where this property failed validation
// passedEventIds: ["abc123"] // Event IDs where this property passed validation
// }
`
Note: Awaiting will block until the event spec is fetched (if not cached) and validation completes. For production use, fire-and-forget is recommended to avoid impacting your application's performance.
In order to ensure our SDK doesn't have a large impact on performance or battery life it supports event schemas batching.
Default batch size is 30 and default batch flush timeout is 30 seconds.
In development mode batching is disabled.
`javascript`
inspector.setBatchSize(15);
inspector.setBatchFlushSeconds(10);
You can control the network timeout for the SDK. Default is 2 seconds.
`javascript``
Inspector.AvoInspector.networkTimeout = 5000;
Avo (https://www.avo.app), friends@avo.app
AvoInspector is available under the MIT license.