browser.history

설명

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

권한

history

사용자의 방문 기록과 상호작용하려면 history API를 사용하세요.

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

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

개념 및 사용법

전환 유형

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

예

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

유형

HistoryItem

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

속성

  • id

    문자열

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

  • lastVisitTime

    number 선택사항

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

  • 제목

    문자열 선택사항

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

  • typedCount

    number 선택사항

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

  • URL

    문자열 선택사항

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

  • visitCount

    number 선택사항

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

TransitionType

Chrome 44 이상 브라우저.*(Chrome 148부터)

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

열거형

'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 이상 브라우저(Chrome 148 이후).*

속성

  • URL

    문자열

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

VisitItem

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

속성

  • id

    문자열

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

  • isLocal

    부울

    Chrome 115 이상 Chrome 148 이후 browser.*

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

  • referringVisitId

    문자열

    리퍼러의 방문 ID입니다.

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

  • visitId

    문자열

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

  • visitTime

    number 선택사항

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

메서드

addUrl()

browser.history.addUrl(
  details: UrlDetails,
): Promise<void>

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

매개변수

반환 값

  • 약속<void>

    Chrome 96 이상 브라우저.*(Chrome 148부터)

deleteAll()

browser.history.deleteAll(): Promise<void>

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

반환 값

  • 약속<void>

    Chrome 96 이상 브라우저.*(Chrome 148부터)

deleteRange()

browser.history.deleteRange(
  range: object,
): Promise<void>

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

매개변수

  • 범위

    객체

    • endTime

      숫자

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

    • startTime

      숫자

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

반환 값

  • 약속<void>

    Chrome 96 이상 브라우저.*(Chrome 148부터)

deleteUrl()

browser.history.deleteUrl(
  details: UrlDetails,
): Promise<void>

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

매개변수

반환 값

  • 약속<void>

    Chrome 96 이상 브라우저.*(Chrome 148부터)

getVisits()

browser.history.getVisits(
  details: UrlDetails,
): Promise<VisitItem[]>

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

매개변수

반환 값

  • Promise<VisitItem[]>

    Chrome 96 이상 브라우저.*(Chrome 148부터) 
browser.history.search(
  query: object,
): Promise<HistoryItem[]>

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

매개변수

  • query

    객체

    • endTime

      number 선택사항

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

    • maxResults

      number 선택사항

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

    • startTime

      number 선택사항

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

    • 텍스트

      문자열

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

반환 값

  • Promise<HistoryItem[]>

    Chrome 96 이상 브라우저.*(Chrome 148부터)

이벤트

onVisited

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

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

매개변수

  • callback

    함수

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

    (result: HistoryItem) => void

onVisitRemoved

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

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

매개변수

  • callback

    함수

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

    (removed: object) => void

    • 삭제됨

      객체

      • allHistory

        부울

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

      • URL

        string[] 선택사항