Web Agent 설치 가이드

<script src="https://cdn.imqa.io/release/npm/@web-agent/latest/index.js">
</script>
<script>
  window.IMQA.init({
    collectorUrl: '{{IMQA_TRACES_COLLECTOR_URL}}',
    serviceName: '{{NAME_OF_YOUR_WEB_SERVICE}}',
    serviceVersion: '{{VERSION_OF_YOUR_WEB_SERVICE}}',
    serviceKey: '{{KEY_OF_YOUR_WEB_SERVICE}}'
    serviceNamespace: '{{SERVICE_NAMESPACE}}',
    deploymentEnvironment: '{{DEPLOYMENT_ENVIRONMENT}}',
  });
</script>

<script
  src="https://cdn.imqa.io/release/npm/@web-agent/{{VERSION}}/index.js"
  integrity="{{VERSION_SRI_HASH_INTEGRITY}}"
  crossorigin="anonymous">
</script>
<script>
    window.IMQA.init({
      collectorUrl: '{{IMQA_TRACES_COLLECTOR_URL}}',
      serviceName: '{{NAME_OF_YOUR_WEB_SERVICE}}',
      serviceVersion: '{{VERSION_OF_YOUR_WEB_SERVICE}}',
      serviceKey: '{{KEY_OF_YOUR_WEB_SERVICE}}'
      serviceNamespace: '{{SERVICE_NAMESPACE}}',
      deploymentEnvironment: '{{DEPLOYMENT_ENVIRONMENT}}',
    });
</script>

import IMQA from '@imqa/web-agent';

IMQA.init({
  collectorUrl: '{{IMQA_TRACES_COLLECTOR_URL}}',
  serviceName: '{{NAME_OF_YOUR_WEB_SERVICE}}',
  serviceVersion: '{{VERSION_OF_YOUR_WEB_SERVICE}}',
  serviceKey: '{{KEY_OF_YOUR_WEB_SERVICE}}',
  serviceNamespace: '{{SERVICE_NAMESPACE}}',
  deploymentEnvironment: '{{DEPLOYMENT_ENVIRONMENT}}',
});

<script src="./public/imqa-agent.js">
</script>
<script>
  window.IMQA.init({
    collectorUrl: '{{IMQA_TRACES_COLLECTOR_URL}}',
    serviceName: '{{NAME_OF_YOUR_SERVICE}}',
    serviceVersion: '{{VERSION_OF_YOUR_SERVICE}}',
    serviceKey: '{{KEY_OF_YOUR_SERVICE}}',
    serviceNamespace: '{{SERVICE_NAMESPACE}}',
    deploymentEnvironment: '{{DEPLOYMENT_ENVIRONMENT}}',
  });
</script>

npm install @imqa/web-agent

yarn add @imqa/web-agent

import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { App } from "./my-app";
import IMQA from "@imqa/web-agent";

IMQA.init({
  collectorUrl: '{{IMQA_TRACES_COLLECTOR_URL}}',
  serviceName: '{{NAME_OF_YOUR_SERVICE}}',
  serviceVersion: '{{VERSION_OF_YOUR_SERVICE}}',
  serviceKey: '{{KEY_OF_YOUR_SERVICE}}',
  serviceNamespace: '{{SERVICE_NAMESPACE}}',
  deploymentEnvironment: '{{DEPLOYMENT_ENVIRONMENT}}',
});

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <App />
  </StrictMode>
);

import Vue from "vue";
import App from "./app.vue"; // get root module
import router from "./router";
import store from "./store"; // get vuex -> store
import IMQA from "@imqa/web-agent"; // IMQA agent

IMQA.init({
  collectorUrl: '{{IMQA_TRACES_COLLECTOR_URL}}',
  serviceName: '{{NAME_OF_YOUR_SERVICE}}',
  serviceVersion: '{{VERSION_OF_YOUR_SERVICE}}',
  serviceKey: '{{KEY_OF_YOUR_SERVICE}}',
  serviceNamespace: '{{SERVICE_NAMESPACE}}',
  deploymentEnvironment: '{{DEPLOYMENT_ENVIRONMENT}}',
});

const app = new Vue({
  router,
  store,
  render: (h) => h(App),
}).$mount("#app");

npm install /path/to/imqa-web-agent-latest.tgz

.
├── README.md
├── index.html
├── package-lock.json
├── package.json
├── public
│   └── vite.svg
├── src
│   ├── App.vue
│   ├── assets
│   │   └── vue.svg
│   ├── components
│   │   └── HelloWorld.vue
│   ├── main.ts
│   ├── style.css
│   └── vite-env.d.ts
├── third-pary-packages
│   └── imqa
│       └── imqa-web-agent-latest.tgz
├── tsconfig.app.json
├── tsconfig.json
├── tsconfig.node.json
└── vite.config.ts

npm install ./third-pary-packages/imqa/imqa-web-agent-latest.tgz

node_modules/@imqa/web-agent
├── CHANGELOG.md
├── README.md
├── build
│   ├── index.d.ts
│   ├── index.js
│   └── sri-hash.txt
└── package.json

npm install @imqa/web-agent

import IMQA from "@imqa/web-agent/legacy";

IMQA.init({
  collectorUrl: '{{IMQA_TRACES_COLLECTOR_URL}}',
  serviceName: '{{NAME_OF_YOUR_WEB_SERVICE}}',
  serviceVersion: '{{VERSION_OF_YOUR_WEB_SERVICE}}',
  serviceKey: '{{KEY_OF_YOUR_WEB_SERVICE}}',
  serviceNamespace: '{{SERVICE_NAMESPACE}}',
  deploymentEnvironment: '{{DEPLOYMENT_ENVIRONMENT}}',
  // 기타 설정...
});

<script
  src="https://cdn.imqa.io/release/npm/@web-agent/latest/index-legacy.js"
  type="text/javascript"></script>
<script>
window.IMQA.init({
  collectorUrl: '{{IMQA_TRACES_COLLECTOR_URL}}',
  serviceName: '{{NAME_OF_YOUR_WEB_SERVICE}}',
  serviceVersion: '{{VERSION_OF_YOUR_WEB_SERVICE}}',
  serviceKey: '{{KEY_OF_YOUR_WEB_SERVICE}}'
  serviceNamespace: '{{SERVICE_NAMESPACE}}',
  deploymentEnvironment: '{{DEPLOYMENT_ENVIRONMENT}}',
  // 기타 설정...
});
</script>

npm install @imqa/vite-sourcemap --save-dev

// vite.config.ts
import { defineConfig } from 'vite'
import sourcemapUpload from '@imqa/vite-sourcemap'

export default defineConfig({
  build: {
    sourcemap: true, // 중요: 소스맵 생성을 활성화해야 합니다
  },
  plugins: [
    sourcemapUpload({
      endpoint: 'https://api.your-service.imqa.io/api/sourcemaps',
      apiKey: process.env.SOURCEMAP_API_KEY,
      release: process.env.GIT_SHA,
      appVersion: process.env.npm_package_version,
    }),
  ],
})

// vite.config.ts
import sourcemapUpload from '@imqa/vite-sourcemap'

export default defineConfig({
  build: {
    sourcemap: true,
  },
  plugins: [
    sourcemapUpload({
      // 필수: 업로드 엔드포인트
      endpoint: 'https://api.your-service.imqa.io/api/sourcemaps',

      // 인증
      apiKey: process.env.IMQA_AUTH_TOKEN,

      // 릴리즈 정보
      release: process.env.IMQA_SERVICE_NAME,
      appVersion: process.env.npm_package_version,

      // CDN 경로 설정
      urlPrefix: '~/dist/',

      // 파일 필터링: assets 폴더의 JS 소스맵만
      include: [/assets\/.+\.js\.map$/],
      exclude: [/node_modules/],

      // CI에서만 실행
      ciOnly: true,

      // 업로드 후 로컬 파일 삭제
      deleteAfterUpload: true,
    }),
  ],
})

# .github/workflows/deploy.yml
- name: Build and upload sourcemaps
  env:
    SOURCEMAP_API_KEY: ${{ secrets.SOURCEMAP_API_KEY }}
    GIT_SHA: ${{ github.sha }}
  run: npm run build

type StorageType = 'cookie' | 'localStorage';

IMQA.init({
  collectorUrl: '{{IMQA_TRACES_COLLECTOR_URL}}',
  serviceName: '{{NAME_OF_YOUR_WEB_SERVICE}}',
  serviceVersion: '{{VERSION_OF_YOUR_WEB_SERVICE}}',
  serviceKey: '{{SERVICE_KEY}}',
  sessionStorage: 'localStorage' // or 'cookie'
});

type ScreenNameType = 'routeOnly' | 'titleOnly' | 'full';

type ScreenNameOption = {
  screenNameType?: ScreenNameType; // default: 'routeOnly'
  urlWithSearchParams?: boolean; // default: false
};

IMQA.init({
  collectorUrl: '{{IMQA_TRACES_COLLECTOR_URL}}',
  serviceName: '{{NAME_OF_YOUR_WEB_SERVICE}}',
  serviceVersion: '{{VERSION_OF_YOUR_WEB_SERVICE}}',
  serviceKey: '{{KEY_OF_YOUR_WEB_SERVICE}}'
  screenNameOption: {
    screenNameType: 'titleOnly', // 타이틀만 포함
    urlWithSearchParams: true // 쿼리 파라미터 추가
  }
});

interface IMQAConsoleInstrumentationConfig
  extends InstrumentationConfig {
  betaMode: boolean;
  loggerOptions: LoggerOptions;
  contextManager?: MutableAsyncLocalStorageContextManager;
}

interface IMQADocLoadInstrumentationConfig
  extends InstrumentationConfig {
  ignoreUrls?: (string | RegExp)[];
}

type IMQAFetchInstrumentationConfig = {
  advancedNetworkCapture?: () => boolean;
  clearTimingResources?: boolean;
  propagateTraceHeaderCorsUrls?: web.PropagateTraceHeaderCorsUrls;
  ignoreUrls?: Array<string | RegExp>;
  applyCustomAttributesOnSpan?: FetchCustomAttributeFunction;
  ignoreNetworkEvents?: boolean;
  measureRequestSize?: boolean;
}

interface UserInteractionInstrumentationConfig extends InstrumentationConfig {
    eventNames?: EventName[];
    shouldPreventSpanCreation?: ShouldPreventSpanCreation;
    events?: UserInteractionEventsConfig;
}

type UserInteractionEventsConfig = {
  [type: string]: boolean;
};
const DEFAULT_AUTO_INSTRUMENTED_EVENTS: UserInteractionEventsConfig = {
  // pointer
  click: true,
  dblclick: true,
  mousedown: true,
  mouseup: true,

  // form
  submit: true,
  reset: true,
  change: true,

  // drap & drop
  dragend: true,
  drop: true,

  // media
  ended: true,
  pause: true,
  play: true,
};

export interface InstrumentationConfig {
    enabled?: boolean;
}

export interface InstrumentationConfig {
    enabled?: boolean;
}

export interface InstrumentationConfig {
    enabled?: boolean;
}

interface IMQAPostDocLoadResourceInstrumentationConfig
  extends InstrumentationConfig {
  allowedInitiatorTypes?: string[];
  ignoreUrls?: (string | RegExp)[];
}

interface SocketIoClientInstrumentationConfig
  extends InstrumentationConfig {
  target?: string | SocketIOClient;
}

interface IMQAWebSocketInstrumentationConfig extends InstrumentationConfig {
  ignoreUrls?: (string | RegExp)[];
}

interface InstrumentationConfig {
  enabled?: boolean;
}

interface XMLHttpRequestInstrumentationConfig extends InstrumentationConfig {
    clearTimingResources?: boolean;
    propagateTraceHeaderCorsUrls?: PropagateTraceHeaderCorsUrls;
    ignoreUrls?: Array<string | RegExp>;
    applyCustomAttributesOnSpan?: XHRCustomAttributeFunction;
    ignoreNetworkEvents?: boolean;
    measureRequestSize?: boolean;
    advancedNetworkCapture?: () => boolean;
}

IMQA.init(config: IMQASDKConfig): void

IMQA.stopSessionRecorder(): void

IMQA.resumeSessionRecorder(): void

IMQA.addAction(name: string, attributes?: Attributes): void

IMQA.addAction('Form-Completed', {
  formId: 'signup-form',
  formName: 'Signup Form',
  formType: 'signup',
});

IMQA.recordException(error: any, attributes?: Attributes): void

IMQA.recordLog(message: string, attributes?: Record<string, string>): void

IMQA.recordLog('API 사용량 초과', {
  userId: 'user_123',
  url: 'https://api.imqa.io/usage',
})

userEvent: {
  start(name?: string, attributes?: Attributes): string;
  end(id: string, attributes?: Attributes): void;
  getActive(): UserEventInstance | undefined;
  cancel(id: string): void;
}

IMQA.setScreenAttribute(name: string): void

/**
 * `setScreenAttribute` 함수는 전달된 속성 값을 저장하고, 마지막 URL을 전역 변수에 기록합니다.
 *
 * @param {string} attribute - `attribute` 매개변수는 화면(screen)에 설정하고자 하는 속성을 나타내는 문자열입니다.
 */
function setScreenAttribute(attribute: string) {
  savedScreenAttribute = attribute;
  lastUrl = window?.location?.href;
}

IMQA.enableAdvancedNetworkCapture(): void

IMQA.disableAdvancedNetworkCapture(): void

IMQA.setGlobalAttributes(attributes: Record<string, string>): void

IMQA.setGlobalAttributes({
  teamName: "your-team-name",
  groupName: "your-group-name",
  // 기타 사용자 지정 속성...
});

setUserIdAttribute(userId: string): void

window.IMQA.setUserIdAttribute("_imqa_user_0001");

setAreaCodeAttribute(areaCode: string): void

IMQA.userEvent.start(name?: string, attributes?: Attributes): string

IMQA.userEvent.end(id: string, attributes?: Attributes): void

IMQA.userEvent.getActive(): UserEventInstance | undefined

IMQA.userEvent.cancel(id: string): void

// 버튼 클릭 이벤트 추적
function handleButtonClick() {
  // 이벤트 시작
  const eventId = IMQA.userEvent.start('button-click', {
    'button.name': 'submit',
    'page.url': window.location.href,
  });

  // 비즈니스 로직 실행
  performBusinessLogic()
    .then(result => {
      // 성공 시 이벤트 완료
      IMQA.userEvent.end(eventId, {
        'action.result': 'success',
        'items.count': result.count,
      });
    })
    .catch(error => {
      // 에러 시 이벤트 완료
      IMQA.userEvent.end(eventId, {
        'action.result': 'error',
        'error.message': error.message,
      });
    });
}

// 폼 제출 이벤트 추적
function handleFormSubmit() {
  const eventId = IMQA.userEvent.start('form-submission', {
    'form.type': 'contact',
    'form.fields': 'name,email,message',
  });

  try {
    validateForm();
    submitForm();

    IMQA.userEvent.end(eventId, {
      'submission.result': 'success',
    });
  } catch (error) {
    IMQA.userEvent.end(eventId, {
      'submission.result': 'error',
      'error.type': error.constructor.name,
    });
    throw error;
  }
}

// 이벤트 취소 예시
function handleCancellableOperation() {
  const eventId = IMQA.userEvent.start('file-upload');

  // 사용자가 취소한 경우
  if (userCancelled) {
    IMQA.userEvent.cancel(eventId);
    return;
  }

  // 정상 처리
  uploadFile().then(() => {
    IMQA.userEvent.end(eventId);
  });
}

getSessionId(): string | undefined

const sessionId = IMQA.getSessionId();

getSessionUrl(): string | undefined

// ErrorBoundary를 가져옵니다 (react-error-boundary를 예제로 사용) 
import { ErrorBoundary } from 'react-error-boundary';
 
// 여기서 ErrorBoundary 컴포넌트에 연결되어
// 해당 컴포넌트 내에서 발생하는 모든 오류를 감지합니다.
IMQA.attachToReactErrorBoundary(ErrorBoundary);

attachToReactErrorBoundary(errorBoundary: ErrorBoundaryComponent): void

// ErrorBoundary 가져오기 (예시로 react-error-boundary를 사용)
import { ErrorBoundary } from 'react-error-boundary';

// ErrorBoundary 컴포넌트에 연결하여 모든 인스턴스에서 발생하는 오류를 캡처합니다.
IMQA.attachToReactErrorBoundary(ErrorBoundary);

var cors = require('cors');
var onHeaders = require('on-headers');

// ... 기타 코드

app.use(function (req, res, next) {
  onHeaders(res, function () {
    var allowOrigin = res.getHeader('Access-Control-Allow-Origin');
    if (allowOrigin) {
      res.setHeader('Timing-Allow-Origin', allowOrigin);
    }
  });
  next();
});
app.use(cors());

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>IMQA Agent Test Example</title>
    <script
      src="https://cdn.imqa.io/release/npm/@web-agent/latest/index.js"
      crossorigin="anonymous">
    </script>
    <script>
      IMQA.init({
        collectorUrl: "https://in-otel.imqa.io",
        serviceName: "your-service-name",
        serviceKey: "YOUR_SERVICE_KEY",
        serviceVersion: "1.0.0"
      });
    </script>
  </head>
  <body>
    <h1>IMQA Agent Test Example</h1>
    <button id="work-btn">Do Work</button>
    <button id="error-btn">Throw Error</button>
    <button id="fetch-btn">Fetch Data</button>
    <button id="xhr-btn">XHR</button>
    <p>Click the buttons to test IMQA tracing and error reporting.</p>
  </body>
  <script>
    // console instrumentation
    function doWork() {
      console.log("Work is done and span is ended");
    }
    // error instrumentation
    function throwError() {
      throw new Error("Test Error");
    }
    // xhr instrumentation
    function xhrBtn() {
      console.log("xhrBtn");
      const xhr = new XMLHttpRequest();
      xhr.open("GET", "https://jsonplaceholder.typicode.com/todos/1");
      xhr.onload = function () {
        if (xhr.status === 200) {
          console.log(xhr.response);
        }
      };
      xhr.send();
    }
    // fetch instrumentation
    function fetchBtn() {
      console.log("fetchBtn");
      fetch("https://jsonplaceholder.typicode.com/todos/1")
        .then(function (response) {
          return response.json();
        })
        .then(function (json) {
          console.log(json);
        });
    }
    // Attach event handlers
    window.onload = () => {
      document.getElementById("work-btn").addEventListener("click", () => {
        doWork();
      });
      document.getElementById("error-btn").addEventListener("click", () => {
        throwError();
      });
      document.getElementById("xhr-btn").addEventListener("click", () => {
        xhrBtn();
      });
      document.getElementById("fetch-btn").addEventListener("click", () => {
        fetchBtn();
      });
    };
  </script>
</html>