chrome.history

설명

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

권한

history

사용자의 브라우저 기록과 상호작용하려면 History API를 사용하세요.

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

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

개념 및 사용법

전환 유형

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

예

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