ainamika-sdk 1.2.9 → 1.3.0

package/README.md

@@ -37,23 +37,27 @@ Or via CDN:
 
 ## Quick Start
 
-### 1. Get Your Project Key
+### 1. Get Your Project Credentials
 
-Sign up at [AInamika Dashboard](https://ainamika.netlify.app) and create a project to get your `projectKey`.
+Sign up at [AInamika Dashboard](https://ainamika.netlify.app) and create a project to get your:
+- **Project Key** (`projectKey`): Public identifier for your project
+- **Project Secret** (`projectSecret`): Secret key for HMAC authentication (shown only once on creation!)
+
+> ⚠️ **Important**: Save your `projectSecret` immediately when creating a project. It's only shown once and cannot be retrieved later (you can regenerate it from project settings).
 
 ### 2. Initialize the SDK
 
 #### Minimal Configuration (Recommended Start)
 
-The simplest way to get started - just 3 lines:
+The simplest way to get started:
 
 ```javascript
 import AInamikaSDK from 'ainamika-sdk';
 
 const analytics = new AInamikaSDK({
-  projectKey: 'proj_xxxxxxxxxx',   // Get this from your dashboard
-  autoConfig: true,                // AI-powered auto-configuration
-  clientId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'  // Your client ID
+  projectKey: 'proj_xxxxxxxxxx',      // Your project key (public)
+  projectSecret: 'your_secret_here',  // Your project secret (keep private!)
+  autoConfig: true                    // AI-powered auto-configuration
 });
 ```
 
@@ -67,10 +71,10 @@ For more control, you can configure all options:
 import AInamikaSDK from 'ainamika-sdk';
 
 const analytics = new AInamikaSDK({
-  projectKey: 'proj_xxxxxxxxxx',  // Get this from your dashboard
-  autoConfig: true,               // AI-powered auto-configuration
-  clientId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
-  debug: false,                   // Set to true for development
+  projectKey: 'proj_xxxxxxxxxx',      // Your project key (public)
+  projectSecret: 'your_secret_here',  // Your project secret (keep private!)
+  autoConfig: true,                   // AI-powered auto-configuration
+  debug: false,                       // Set to true for development
 
   // Extra config - custom data included with ALL events
   extraConfig: {
@@ -308,12 +312,12 @@ analytics.trackConversion('newsletter_subscribe', undefined, {
 
 ```javascript
 const analytics = new AInamikaSDK({
-  // Required for authentication
-  projectKey: 'proj_xxxxxxxxxx',    // Get from your dashboard
-  clientId: 'your-client-id',       // Your unique client identifier
+  // Required - Authentication (HMAC)
+  projectKey: 'proj_xxxxxxxxxx',      // Your project key (public)
+  projectSecret: 'your_secret_here',  // Your project secret (keep private!)
 
   // Auto-Configuration
-  autoConfig: true,                 // Enable AI-powered DOM analysis
+  autoConfig: true,                   // Enable AI-powered DOM analysis
 
   // Debugging
   debug: false,                     // Enable console logging
@@ -405,7 +409,7 @@ Pass custom data that will be included with **every event**. This is useful for
 // Set during initialization
 const analytics = new AInamikaSDK({
   projectKey: 'proj_xxxxxxxxxx',
-  clientId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
+  projectSecret: 'your_secret_here',
   autoConfig: true,
   extraConfig: {
     appVersion: '2.0.0',
@@ -581,7 +585,7 @@ import { useEffect } from 'react';
 
 const analytics = new AInamikaSDK({
   projectKey: 'proj_xxxxxxxxxx',
-  clientId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
+  projectSecret: 'your_secret_here',  // Keep this secure!
   autoConfig: true,
   extraConfig: {
     appVersion: '2.0.0',
@@ -622,8 +626,8 @@ let analytics = null;
 export function getAnalytics() {
   if (typeof window !== 'undefined' && !analytics) {
     analytics = new AInamikaSDK({
-      projectKey: 'proj_xxxxxxxxxx',
-      clientId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
+      projectKey: process.env.NEXT_PUBLIC_AINAMIKA_PROJECT_KEY,
+      projectSecret: process.env.NEXT_PUBLIC_AINAMIKA_PROJECT_SECRET,  // Keep secure!
       autoConfig: true,
       extraConfig: {
         appVersion: process.env.NEXT_PUBLIC_APP_VERSION || '1.0.0',
@@ -670,10 +674,10 @@ function MyApp({ Component, pageProps }) {
   <button id="game-btn" customdata='{"name":"Puzzle Master"}'>Play Game</button>
 
   <script>
-    // Minimal setup - just 3 required fields
+    // Initialize with project credentials
     const analytics = new AInamikaSDKPro({
       projectKey: 'proj_xxxxxxxxxx',
-      clientId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
+      projectSecret: 'your_secret_here',  // Keep this secure!
       autoConfig: true,
 
       // Optional: Add extra config for better tracking
@@ -739,9 +743,27 @@ function MyApp({ Component, pageProps }) {
 2. Use `trackAPI()` for manual tracking
 3. Check `apiTrackingPatterns` if using filters
 
-## Data Privacy
+## Security & Data Privacy
+
+### HMAC Authentication
+
+The SDK uses HMAC-SHA256 signatures for secure API authentication:
+- Every request is signed with your `projectSecret`
+- Signatures include timestamps to prevent replay attacks
+- The secret is never transmitted - only used to generate signatures
+
+### Protecting Your Project Secret
+
+⚠️ **Important**: Keep your `projectSecret` secure:
+- Never commit it to public repositories
+- Use environment variables in production
+- For client-side apps, consider using a backend proxy for sensitive operations
+- Regenerate the secret from the dashboard if compromised
+
+### Data Privacy
 
 - All data is transmitted securely over HTTPS
+- Requests are signed with HMAC-SHA256
 - User identifiers are hashed before transmission
 - Sampling can reduce data collection
 - No PII is collected automatically