chrome.history

refresh date: 2026-09-25 robots: noindex

설명

chrome.history API를 사용하여 방문한 페이지의 브라우저 기록과 상호작용합니다. 브라우저 기록에서 URL을 추가, 삭제, 쿼리할 수 있습니다. 방문 기록 페이지를 자체 버전으로 재정의하려면 페이지 재정의를 참고하세요.

권한

history

매니페스트

history API를 사용하려면 확장 프로그램 매니페스트에서 'history' 권한을 선언해야 합니다. 예를 들면 다음과 같습니다.

{
  "name": "My extension",
  ...
  "permissions": [
    "history"
  ],
  ...
}

전환 유형

History API는 전환 유형을 사용하여 브라우저가 특정 방문에서 특정 URL로 이동한 방식을 설명합니다. 예를 들어 사용자가 다른 페이지의 링크를 클릭하여 페이지를 방문하는 경우 전환 유형은 'link'입니다.

다음 표에서는 각 전환 유형을 설명합니다.

전환 유형설명
'typed'사용자가 주소 표시줄에 URL을 입력하여 이 페이지로 이동했습니다. 다른 명시적 탐색 작업에도 사용됩니다. 사용자가 URL과 전혀 유사하지 않은 선택지를 선택한 경우에 사용되는 generated도 참고하세요.
"auto_bookmark"사용자가 UI의 추천(예: 메뉴 항목)을 통해 이 페이지로 이동했습니다.
thought 'auto_subframe'하위 프레임 탐색 최상위 프레임이 아닌 프레임에 자동으로 로드되는 모든 콘텐츠입니다. 예를 들어 페이지가 광고를 포함하는 여러 프레임으로 구성된 경우 해당 광고 URL은 이 전환 유형을 갖습니다. 사용자는 이러한 페이지의 콘텐츠가 별도의 프레임이라는 사실을 인식하지 못할 수 있으므로 URL에 신경 쓰지 않을 수 있습니다(manual_subframe도 참고).
"manual_subframe"사용자가 명시적으로 요청하고 뒤로/앞으로 목록에 새 탐색 항목을 생성하는 하위 프레임 탐색의 경우 명시적으로 요청된 프레임은 자동으로 로드된 프레임보다 더 중요할 수 있습니다. 사용자가 요청된 프레임이 로드되었다는 사실에 관심을 가질 수 있기 때문입니다.
'generated'사용자가 주소 표시줄에 입력하고 URL처럼 보이지 않는 항목을 선택하여 이 페이지로 이동했습니다. 예를 들어 일치 항목에 Google 검색 결과 페이지의 URL이 있을 수 있지만 사용자에게는 'Google에서 … 검색'으로 표시될 수 있습니다. 사용자가 도착 URL을 입력하거나 보지 않았으므로 이는 입력된 탐색과 완전히 동일하지는 않습니다. 키워드도 참고하세요.
"auto_toplevel"페이지가 명령줄에 지정되었거나 시작 페이지입니다.
"form_submit"사용자가 양식에 값을 입력하고 제출했습니다. 양식에서 스크립트를 사용하여 콘텐츠를 제출하는 경우와 같은 일부 상황에서는 양식을 제출해도 이 전환 유형이 발생하지 않습니다.
'reload'사용자가 새로고침 버튼을 클릭하거나 주소 표시줄에서 Enter 키를 눌러 페이지를 새로고침했습니다. 세션 복원 및 닫은 탭 다시 열기에서도 이 전환 유형을 사용합니다.
'키워드'기본 검색 서비스 제공업체 이외의 대체 가능한 키워드에서 생성된 URL입니다. keyword_generated도 참고하세요.
'keyword_generated'키워드에 대해 생성된 방문에 해당합니다. 키워드도 참고하세요.

예

이 API를 사용해 보려면 chrome-extension-samples 저장소에서 history API 예를 설치하세요.

유형

HistoryItem

기록 쿼리의 결과 하나를 캡슐화하는 객체입니다.

속성

  • id

    문자열

    항목의 고유 식별자입니다.

  • lastVisitTime

    number 선택사항

    이 페이지가 마지막으로 로드된 시간(에포크 이후 밀리초 단위)입니다.

  • 제목

    문자열 선택사항

    페이지가 마지막으로 로드되었을 때의 페이지 제목입니다.

  • typedCount

    number 선택사항

    사용자가 주소를 입력하여 이 페이지로 이동한 횟수입니다.

  • URL

    문자열 선택사항

    사용자가 이동한 URL입니다.

  • visitCount

    number 선택사항

    사용자가 이 페이지로 이동한 횟수입니다.

TransitionType

Chrome 44 이상

리퍼러에서 이 방문으로의 전환 유형입니다.

열거형

'link'
사용자가 다른 페이지의 링크를 클릭하여 이 페이지에 도달했습니다.

'typed'
사용자가 주소 표시줄에 URL을 입력하여 이 페이지에 도달했습니다. 다른 명시적 탐색 작업에도 사용됩니다.

"auto_bookmark"
사용자가 UI의 추천(예: 메뉴 항목)을 통해 이 페이지에 도달했습니다.

'auto_subframe'
사용자가 요청하지 않은 하위 프레임 탐색을 통해 이 페이지에 도달했습니다(예: 이전 페이지의 프레임에 로드된 광고를 통해). 이러한 작업이 뒤로 및 앞으로 메뉴에 항상 새 탐색 항목을 생성하는 것은 아닙니다.

"manual_subframe"
사용자가 하위 프레임에서 무언가를 선택하여 이 페이지에 도달했습니다.

'generated'
사용자가 주소 표시줄에 입력하고 Google 검색 추천과 같이 URL처럼 보이지 않는 항목을 선택하여 이 페이지에 도달했습니다. 예를 들어 일치하는 항목에 Google 검색 결과 페이지의 URL이 있을 수 있지만 사용자에게는 'Google에서 … 검색'으로 표시될 수 있습니다. 사용자가 도착 URL을 입력하거나 보지 않았으므로 이는 입력된 탐색과 다릅니다. 키워드 탐색과도 관련이 있습니다.

"auto_toplevel"
페이지가 명령줄에 지정되었거나 시작 페이지입니다.

"form_submit"
사용자가 양식에 값을 입력하고 양식을 제출하여 이 페이지에 도달했습니다. 모든 양식 제출이 이 전환 유형을 사용하는 것은 아닙니다.

'reload'
사용자가 새로고침 버튼을 클릭하거나 주소 표시줄에서 Enter 키를 눌러 페이지를 새로고침했습니다. 세션 복원 및 닫은 탭 다시 열기에서도 이 전환 유형을 사용합니다.

"keyword"
이 페이지의 URL은 기본 검색 서비스 제공업체 이외의 대체 가능한 키워드에서 생성되었습니다.

"keyword_generated"
키워드에 대해 생성된 방문에 해당합니다.

UrlDetails

Chrome 88 이상

속성

  • URL

    문자열

    작업의 URL입니다. history.search() 호출에서 반환된 형식이어야 합니다.

VisitItem

URL 방문 1회를 캡슐화하는 객체입니다.

속성

  • id

    문자열

    해당 history.HistoryItem의 고유 식별자입니다.

  • isLocal

    부울

    Chrome 115 이상

    이 기기에서 방문이 시작된 경우 true입니다. 다른 기기에서 동기화된 경우 false입니다.

  • referringVisitId

    문자열

    리퍼러의 방문 ID입니다.

  • 리퍼러에서 이 방문으로의 전환 유형입니다.

  • visitId

    문자열

    이 방문의 고유 식별자입니다.

  • visitTime

    number 선택사항

    이 방문이 발생한 시간으로, 에포크 이후 밀리초 단위로 표시됩니다.

메서드

addUrl()

Promise 
chrome.history.addUrl(
  details: UrlDetails,
  callback?: function,
): Promise<void>

전환 유형이 'link'인 현재 시간의 방문 기록에 URL을 추가합니다.

매개변수

  • 세부정보

    UrlDetails

  • callback

    함수 선택사항

    callback 매개변수는 다음과 같습니다. 

    () => void

반환 값

  • 약속<void>

    Chrome 96 이상

    프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.

deleteAll()

Promise 
chrome.history.deleteAll(
  callback?: function,
): Promise<void>

기록에서 모든 항목을 삭제합니다.

매개변수

  • callback

    함수 선택사항

    callback 매개변수는 다음과 같습니다. 

    () => void

반환 값

  • 약속<void>

    Chrome 96 이상

    프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.

deleteRange()

Promise 
chrome.history.deleteRange(
  range: object,
  callback?: function,
): Promise<void>

지정된 기간 내의 모든 항목을 기록에서 삭제합니다. 모든 방문이 범위 내에 있지 않으면 페이지가 방문 기록에서 삭제되지 않습니다.

매개변수

  • 범위

    객체

    • endTime

      숫자

      이 날짜 이전에 기록에 추가된 항목입니다(에포크 이후의 경과 시간(밀리초)).

    • startTime

      숫자

      이 날짜 이후에 기록에 추가된 항목입니다(에포크 이후 밀리초 단위로 표시).

  • callback

    함수 선택사항

    callback 매개변수는 다음과 같습니다. 

    () => void

반환 값

  • 약속<void>

    Chrome 96 이상

    프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.

deleteUrl()

Promise 
chrome.history.deleteUrl(
  details: UrlDetails,
  callback?: function,
): Promise<void>

방문 기록에서 지정된 URL의 모든 항목을 삭제합니다.

매개변수

  • 세부정보

    UrlDetails

  • callback

    함수 선택사항

    callback 매개변수는 다음과 같습니다. 

    () => void

반환 값

  • 약속<void>

    Chrome 96 이상

    프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.

getVisits()

Promise 
chrome.history.getVisits(
  details: UrlDetails,
  callback?: function,
): Promise<VisitItem[]>

URL 방문에 관한 정보를 가져옵니다.

매개변수

  • 세부정보

    UrlDetails

  • callback

    함수 선택사항

    callback 매개변수는 다음과 같습니다. 

    (results: VisitItem[]) => void

반환 값

  • Promise<VisitItem[]>

    Chrome 96 이상

    프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.

Promise 
chrome.history.search(
  query: object,
  callback?: function,
): Promise<HistoryItem[]>

방문 기록에서 검색어와 일치하는 각 페이지의 마지막 방문 시간을 검색합니다.

매개변수

  • query

    객체

    • endTime

      number 선택사항

      이 날짜 이전에 방문한 결과로 제한합니다(에포크 이후 밀리초 단위로 표시).

    • maxResults

      number 선택사항

      검색할 최대 결과 수입니다. 기본값은 100입니다.

    • startTime

      number 선택사항

      이 날짜 이후에 방문한 결과로 제한합니다(에포크 이후 밀리초 단위로 표시). 속성을 지정하지 않으면 기본값은 24시간입니다.

    • 텍스트

      문자열

      기록 서비스에 대한 자유 텍스트 쿼리입니다. 모든 페이지를 검색하려면 이 입력란을 비워 둡니다.

  • callback

    함수 선택사항

    callback 매개변수는 다음과 같습니다. 

    (results: HistoryItem[]) => void

반환 값

  • Promise<HistoryItem[]>

    Chrome 96 이상

    프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.

이벤트

onVisited

chrome.history.onVisited.addListener(
  callback: function,
)

URL을 방문할 때 실행되며 해당 URL의 HistoryItem 데이터를 제공합니다. 이 이벤트는 페이지가 로드되기 전에 실행됩니다.

매개변수

  • callback

    함수

    callback 매개변수는 다음과 같습니다. 

    (result: HistoryItem) => void

onVisitRemoved

chrome.history.onVisitRemoved.addListener(
  callback: function,
)

하나 이상의 URL이 방문 기록에서 삭제될 때 실행됩니다. 모든 방문 기록이 삭제되면 URL이 방문 기록에서 삭제됩니다.

매개변수

  • callback

    함수

    callback 매개변수는 다음과 같습니다. 

    (removed: object) => void

    • 삭제됨

      객체

      • allHistory

        부울

        모든 기록이 삭제되었으면 True입니다. true이면 URL이 비어 있습니다.

      • URL

        string[] 선택사항