chrome.history

설명

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

권한

history

매니페스트

'기록'을 선언해야 합니다. 기록 API를 사용할 수 있는 확장 프로그램 매니페스트의 권한을 요청합니다. 예를 들면 다음과 같습니다.

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

전환 유형

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

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

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

예

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

유형

HistoryItem

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

속성

  • id

    문자열

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

  • lastVisitTime

    숫자 선택사항

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

  • 제목

    문자열(선택사항)

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

  • typedCount

    숫자 선택사항

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

  • URL

    문자열(선택사항)

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

  • visitCount

    숫자 선택사항

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

TransitionType

Chrome 44 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

리퍼러에서 이 방문에 대한 전환 유형입니다.

열거형

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

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

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

"auto_subframe"
사용자가 이전 페이지의 프레임에서 광고를 로드하는 등 요청하지 않은 하위 프레임 탐색을 통해 이 페이지에 도달했습니다. 이렇게 해도 뒤로/앞으로 메뉴에 새 탐색 항목이 항상 생성되는 것은 아닙니다.

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

'생성됨'
사용자가 주소 표시줄에 입력하고 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()

<ph type="x-smartling-placeholder"></ph> 프로미스 를 통해 개인정보처리방침을 정의할 수 있습니다.
chrome.history.addUrl(
  details: UrlDetails,
  callback?: function,
)

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

매개변수

  • 세부정보

    UrlDetails

  • 콜백

    함수 선택사항

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

    () => void

반환 값

  • 프로미스<void>

    Chrome 96 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

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

deleteAll()

<ph type="x-smartling-placeholder"></ph> 프로미스 를 통해 개인정보처리방침을 정의할 수 있습니다.
chrome.history.deleteAll(
  callback?: function,
)

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

매개변수

  • 콜백

    함수 선택사항

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

    () => void

반환 값

  • 프로미스<void>

    Chrome 96 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

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

deleteRange()

<ph type="x-smartling-placeholder"></ph> 프로미스 를 통해 개인정보처리방침을 정의할 수 있습니다.
chrome.history.deleteRange(
  range: object,
  callback?: function,
)

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

매개변수

  • 범위

    객체

    • endTime

      숫자

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

    • startTime

      숫자

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

  • 콜백

    함수 선택사항

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

    () => void

반환 값

  • 프로미스<void>

    Chrome 96 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

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

deleteUrl()

<ph type="x-smartling-placeholder"></ph> 프로미스 를 통해 개인정보처리방침을 정의할 수 있습니다.
chrome.history.deleteUrl(
  details: UrlDetails,
  callback?: function,
)

기록에서 지정된 URL과 일치하는 모든 항목을 삭제합니다.

매개변수

  • 세부정보

    UrlDetails

  • 콜백

    함수 선택사항

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

    () => void

반환 값

  • 프로미스<void>

    Chrome 96 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

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

getVisits()

<ph type="x-smartling-placeholder"></ph> 프로미스 를 통해 개인정보처리방침을 정의할 수 있습니다.
chrome.history.getVisits(
  details: UrlDetails,
  callback?: function,
)

URL 방문에 대한 정보를 검색합니다.

매개변수

  • 세부정보

    UrlDetails

  • 콜백

    함수 선택사항

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

    (results: VisitItem[]) => void

반환 값

  • Promise&lt;VisitItem[]&gt;

    Chrome 96 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

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

<ph type="x-smartling-placeholder"></ph> 프로미스 를 통해 개인정보처리방침을 정의할 수 있습니다.
chrome.history.search(
  query: object,
  callback?: function,
)

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

매개변수

  • 검색어

    객체

    • endTime

      숫자 선택사항

      이 날짜 이전에 방문한 결과로 결과를 제한하며 에포크 이후 밀리초 단위로 표시됩니다.

    • maxResults

      숫자 선택사항

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

    • startTime

      숫자 선택사항

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

    • 텍스트

      문자열

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

  • 콜백

    함수 선택사항

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

    (results: HistoryItem[]) => void

반환 값

  • Promise&lt;HistoryItem[]&gt;

    Chrome 96 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

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

이벤트

onVisited

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

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

매개변수

  • 콜백

    함수

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

    (result: HistoryItem) => void

onVisitRemoved

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

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

매개변수

  • 콜백

    함수

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

    (removed: object) => void

    • 삭제됨

      객체

      • allHistory

        부울

        모든 기록이 삭제된 경우 true입니다. true인 경우 URL이 비어 있게 됩니다.

      • URL

        string[] 선택사항