iblai-analytics（易卜莱分析）

/iblai-analytics

Add an analytics dashboard with a tabbed layout (AnalyticsLayout): Overview, Courses, Programs, Users, Topics, Financial, Transcripts, Reports. Each tab is a Next.js route under /analytics/.

Analytics Page

Do NOT add custom styles to ibl.ai SDK components. Do NOT implement dark mode unless asked. Follow the component hierarchy: ibl.ai SDK (@iblai/iblai-js) first, then shadcn/ui (npx shadcn@latest add).

Prerequisites

• Auth set up (/iblai-auth)
• MCP and skills set up (iblai add mcp)
• iblai.env populated with PLATFORM, DOMAIN, TOKEN. If missing: curl -o iblai.env https://raw.githubusercontent.com/iblai/vibe/refs/heads/main/iblai.env

Generate

iblai --version    # upgrade if outdated: pip install --upgrade iblai-app-cli OR npm i -g @iblai/cli@latest
iblai add analytics

Generated: app/(app)/analytics/page.tsx (overview only). You create the layout and sub-pages manually.

Layout

Wrap pages with AnalyticsLayout + AnalyticsSettingsProvider. The SDK layout uses bg-[#f5f7fb] internally — wrap it in a white card so it pops against the page background.

// app/(app)/analytics/layout.tsx
"use client";

import { AnalyticsLayout, AnalyticsSettingsProvider } from "@iblai/iblai-js/web-containers";
import { usePathname, useRouter } from "next/navigation";

export default function AnalyticsLayoutWrapper({ children }: { children: React.ReactNode }) {
  const pathname = usePathname();
  const router = useRouter();
  const basePath = "/analytics";

  return (
    <div className="mx-auto w-full flex-1 overflow-auto px-4 py-8 md:w-[75vw] md:px-0">
      <div className="rounded-lg border border-[var(--border-color)] bg-white overflow-hidden">
        <AnalyticsSettingsProvider value={{}}>
          <AnalyticsLayout
            currentPath={pathname}
            basePath={basePath}
            onTabChange={(tab) => router.push(tab ? `${basePath}/${tab}` : basePath)}
          >
            {children}
          </AnalyticsLayout>
        </AnalyticsSettingsProvider>
      </div>
    </div>
  );
}

Sub-pages

All components import from @iblai/iblai-js/web-containers. Pattern:

"use client";
import { useEffect, useState } from "react";
import { AnalyticsCourses } from "@iblai/iblai-js/web-containers";
import { resolveAppTenant } from "@/lib/iblai/tenant";

export default function CoursesPage() {
  const [tenantKey, setTenantKey] = useState("");
  useEffect(() => { setTenantKey(resolveAppTenant()); }, []);
  if (!tenantKey) return null;
  return <AnalyticsCourses tenantKey={tenantKey} mentorId="" basePath="/analytics" />;
}

All accept tenantKey (required) and mentorId="" ("" = org-wide, not undefined). Use MCP for full props: get_component_info("AnalyticsOverview"), etc.

Verify

pnpm build && pnpm test
pnpm dev &
npx playwright screenshot http://localhost:3000/analytics /tmp/analytics.png

Notes

• Redux store must include mentorReducer and mentorMiddleware.
• initializeDataLayer() takes 5 args (data-layer v1.2+).
• @reduxjs/toolkit deduped via webpack aliases in next.config.ts.
• To override the SDK gray background to white, in globals.css: .bg-\[\#f5f7fb\] {background-color: #fff!important;}

Analytics REST API

Base URL: ${dmUrl}/api/ai-analytics/ and ${dmUrl}/api/analytics/ — dmUrl is the first arg passed to initializeDataLayer() (sourced from NEXT_PUBLIC_API_BASE_URL). Auth: Authorization: Token <token> Live OpenAPI: https://api.iblai.app/dm/api/docs/schema/swagger-ui/

Two namespaces: /api/ai-analytics/ (AI/agent analytics — chat, costs, sentiment, topics, traces, audience/engagement/performance dashboards) and /api/analytics/ (LMS analytics — content, financial, ratings, sessions, time, users). Most endpoints scope to {org} (the platform/tenant key).

Prefer SDK RTK Query hooks over hand-rolled fetch. Use get_api_query_info("<hookName>") in MCP to find the relevant hook before writing custom UI.

{user_id} in /api/ai-analytics/orgs/{org}/users/{user_id}/... is the requesting admin's user id (RBAC + audit), not the user being queried — pass that via filter_user_id.

Common query parameters

Audience — /api/ai-analytics/audience/orgs/{org}/

Engagement — /api/ai-analytics/engagement/orgs/{org}/

Overview — /api/ai-analytics/overview/orgs/{org}/

active-users, average-grade, courses/completions, learners, most-active-courses, registered-users — top-level dashboard cards.

Performance — /api/ai-analytics/performance/orgs/{org}/

Per-Learner — /api/ai-analytics/perlearner/orgs/{org}/

AI Mentor / User — /api/ai-analytics/orgs/{org}/users/{user_id}/

Chat history

Mentors, costs, topics, sentiment, usage

Misc

LMS Analytics — /api/analytics/

Accepts date_filter, granularity, metric, mentor_unique_id, platform_key, usergroup_ids, page, limit ≤ 100.

RBAC

Ibl.Analytics/Core/read (viewer) or Ibl.* (tenant admin). Per-learner and chat-history endpoints also require platform admin.

Example

curl "${dmUrl}/api/ai-analytics/audience/orgs/main/active-users/over-time?date_filter=30d" \
  -H "Authorization: Token ${TOKEN}"

curl "${dmUrl}/api/analytics/content/?metric=courses&date_filter=7d&include_overtime=true" \
  -H "Authorization: Token ${TOKEN}"