chrome.history

설명

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

권한

history

매니페스트

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

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

전환 유형

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

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

전환 유형설명
'typed'사용자가 주소 표시줄에 URL을 입력하여 이 페이지를 가져왔습니다. 다른 명시적 탐색 작업에도 사용됩니다. 사용자가 URL과 전혀 유사하지 않은 선택사항을 선택한 경우에 사용되는 generated도 참고하세요.
'auto_bookmark'사용자가 UI의 추천(예: 메뉴 항목)을 통해 이 페이지로 이동했습니다.
'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 example을 설치하세요.

유형

HistoryItem

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

속성

  • id

    문자열

    상품의 고유 식별자입니다.

  • lastVisitTime

    번호 선택사항

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

  • 제목

    문자열 선택사항

    마지막으로 로드된 페이지의 제목입니다.

  • typedCount

    번호 선택사항

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

  • URL

    문자열 선택사항

    사용자가 탐색한 URL입니다.

  • visitCount

    번호 선택사항

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

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 방문을 하나 캡슐화하는 객체입니다.

속성

  • id

    문자열

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

  • isLocal

    부울

    Chrome 115 이상

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

  • referringVisitId

    문자열

    리퍼러의 방문 ID입니다.

  • 리퍼러로부터의 이 방문의 전환 유형입니다.

  • visitId

    문자열

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

  • visitTime

    번호 선택사항

    이 방문이 발생한 시간입니다(에포크 이후 경과된 시간(밀리초)).

메서드

addUrl()

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

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

매개변수

  • 세부정보

    UrlDetails

  • callback

    함수 선택사항

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

    () => void

반환 값

  • Promise<void>

    Chrome 96 이상

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

deleteAll()

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

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

매개변수

  • callback

    함수 선택사항

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

    () => void

반환 값

  • Promise<void>

    Chrome 96 이상

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

deleteRange()

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

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

매개변수

  • 범위

    객체

    • endTime

      숫자

      이 날짜 이전에 기록에 추가된 항목으로, 에포크 이후 경과된 시간(밀리초)으로 표시됩니다.

    • startTime

      숫자

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

  • callback

    함수 선택사항

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

    () => void

반환 값

  • Promise<void>

    Chrome 96 이상

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

deleteUrl()

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

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

매개변수

  • 세부정보

    UrlDetails

  • callback

    함수 선택사항

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

    () => void

반환 값

  • Promise<void>

    Chrome 96 이상

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

getVisits()

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

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

매개변수

  • 세부정보

    UrlDetails

  • callback

    함수 선택사항

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

    (results: VisitItem[]) => void

반환 값

  • Promise<VisitItem[]>

    Chrome 96 이상

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

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

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

매개변수

  • query

    객체

    • endTime

      번호 선택사항

      이 날짜 이전에 방문한 장소로 결과를 제한합니다(에포크 이후 경과 시간(밀리초)).

    • maxResults

      번호 선택사항

      가져올 최대 결과 수입니다. 기본값은 100입니다.

    • startTime

      번호 선택사항

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

    • 텍스트

      문자열

      기록 서비스에 대한 자유 텍스트 쿼리입니다. 모든 페이지를 가져오려면 이 값을 비워 둡니다.

  • callback

    함수 선택사항

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

    (results: HistoryItem[]) => void

반환 값

  • Promise<HistoryItem[]>

    Chrome 96 이상

    Promise는 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[] 선택사항