Class CefriumProfile

java.lang.Object
com.cefrium.CefriumProfile

public final class CefriumProfile extends Object
Where a browser keeps its cookies, local storage, IndexedDB, service workers and cache. Browsers of one profile share that data; browsers of different profiles see none of each other's.

Pass a profile when creating a browser, e.g. CefriumBrowser.createWithSurface(activity, CefriumProfile.get("work")). A named profile lives in profile-<name> under the engine's data directory (Cefrium.setDataDirectory(File)) and persists across starts. incognito() keeps everything in memory and forgets it when its last browser closes.

The engine keeps a profile's databases open once it has been used, so do not copy or delete its directory yourself while the app runs: use delete(String), and back a profile up only from a process that has not opened it.

Methods that return a result must be called on the main thread and throw IllegalStateException on another. Methods that take a callback may be called from any thread; the callback runs on the main thread.

  • Field Details

  • Method Details

    • getDefault

      public static CefriumProfile getDefault()
      The engine's default persistent profile, used when none is given.
    • incognito

      public static CefriumProfile incognito()
      Off the record: in memory only, shared by every incognito browser.
    • get

      public static CefriumProfile get(String name)
      A named persistent profile, created on first use.
      Parameters:
      name - letters, digits, - and _, 1 to 64 characters.
      Throws:
      IllegalArgumentException - for any other name.
    • getName

      public String getName()
      Returns:
      the profile's name, or null for the default and incognito profiles.
    • isIncognito

      public boolean isIncognito()
      Returns:
      true for incognito().
    • getDirectory

      public File getDirectory()
      Returns:
      where this profile's data lives: the engine's data directory for the default profile, profile-<name> under it for a named one, null for incognito.
      Throws:
      IllegalStateException - if the engine cannot start.
    • delete

      public static boolean delete(String name)
      Deletes a named profile's data.
      Returns:
      true if the data was deleted now; false if the profile was used in this run, in which case the engine still holds its databases open and the data is deleted on the next start, before the engine opens anything.
      Throws:
      IllegalStateException - if a browser of this profile is open, or if the engine cannot start.
    • listSiteData

      public void listSiteData(CefriumProfile.SiteDataCallback callback)
      Lists every site that has data in this profile, with its size and cookie count: the same figures Chrome's per-site storage screen shows.
      Throws:
      IllegalStateException - if the engine cannot start.
    • clearSiteData

      public void clearSiteData(String site, Runnable done)
      Deletes everything this profile holds for site: cookies, local and session storage, IndexedDB, Cache Storage, service workers and the other per-site stores. site is a value from listSiteData(CefriumProfile.SiteDataCallback) or an origin URL such as https://example.com, which also covers the data Chromium keeps under that host.
      Parameters:
      done - runs on the UI thread once the data is gone; may be null.
      Throws:
      IllegalStateException - if the engine cannot start.
    • followDefaultProfile

      public void followDefaultProfile()
      For the incognito profile: drops the proxy and WebRTC settings set on it, so it follows the default profile's again. Does nothing on other profiles.
    • setProxy

      @Deprecated public boolean setProxy(String mode, String server)
      Routes this profile's traffic through a proxy. mode is one of the CefriumBrowser.PROXY_* constants; server is "host:port" or "scheme://host:port" (e.g. "socks5://127.0.0.1:9050") for PROXY_FIXED, the PAC URL for PROXY_PAC, and ignored otherwise.

      A fixed proxy has no direct fallback: when it cannot be reached, requests fail instead of leaving without it. Loopback addresses (localhost, 127.0.0.1) are never proxied, as in Chrome. WebRTC is not covered by a proxy; see setWebRtcIpHandlingPolicy(CefriumWebRtcIpPolicy).

      Returns:
      false if the engine rejected the setting.
    • setProxy

      @CefriumExperimental public boolean setProxy(CefriumProxyMode mode, String server)
      Routes this profile's traffic as mode says; server is "host:port" or "scheme://host:port" (e.g. "socks5://127.0.0.1:9050") for CefriumProxyMode.FIXED, the PAC URL for CefriumProxyMode.PAC, and ignored otherwise. See setProxy(String, String) for what a proxy covers.
      Returns:
      false if the engine rejected the setting.
    • setProxy

      public boolean setProxy(String server)
    • clearProxy

      public boolean clearProxy()
      Direct connections again.
    • setWebRtcIpHandlingPolicy

      @CefriumExperimental public boolean setWebRtcIpHandlingPolicy(CefriumWebRtcIpPolicy policy)
      Which interfaces WebRTC may use; see CefriumWebRtcIpPolicy.
    • setWebRtcIpHandlingPolicy

      @Deprecated public boolean setWebRtcIpHandlingPolicy(String policy)
      Which network interfaces and transports WebRTC may use. A proxy does not carry WebRTC's UDP, so with a proxy alone a page can still learn the device's address through a peer connection. With WEBRTC_DISABLE_NON_PROXIED_UDP WebRTC uses no UDP that bypasses the proxy, and gathers no local or public address candidates.
      Returns:
      false if the engine rejected the setting.
    • registerContentServer

      public void registerContentServer(String origin, CefriumContentServer server)
      Serves an https origin from the app: every request this profile's browsers, workers and service workers make to it goes to server, and none reaches the network. The origin keeps its storage across launches, as any origin, and is a secure context.
      CefriumProfile.getDefault().registerContentServer("https://app.local",
              CefriumContentServers.assets(context, "www"));
      browser.loadUrl("https://app.local/index.html");
      

      Pick a host that is not a real site, or one the app owns: requests to it never leave the device while the server is registered. Use CefriumContentServers.WEBVIEW_ASSET_LOADER_ORIGIN to keep a WebView app's URLs.

      Applies to browsers that already exist and to those created later. Registering the origin again replaces its server. The incognito profile keeps the registration across private sessions.

      Parameters:
      origin - https://<host>, with no port or path.
      server - Answers the requests; see CefriumContentServer.
      Throws:
      IllegalArgumentException - if the origin is not of that form.
    • unregisterContentServer

      public void unregisterContentServer(String origin)
      Stops serving an origin registered with registerContentServer(String, CefriumContentServer); its requests go to the network again.
    • setResourceInterceptor

      @CefriumExperimental public void setResourceInterceptor(CefriumResourceInterceptor interceptor)
      The interceptor for this profile's requests that belong to no browser: a service worker's own requests and its fetches. A browser's requests go to the browser's interceptor (CefriumBrowser.setResourceInterceptor(CefriumResourceInterceptor)). Only CefriumResourceInterceptor.shouldBlockRequest(CefriumBrowser.ResourceRequest) (its request has no document) and CefriumResourceInterceptor.shouldInterceptRequest(CefriumContentRequest) are called. Null removes it. Call on the main thread, before creating the browsers whose pages register the service workers.

      Experimental: it may still change before the 1.0 API freeze.

    • setAdBlockExceptions

      public boolean setAdBlockExceptions(Collection<String> sites)
      Sites where this profile's browsers block nothing, as an @@||site^$document filter rule does: a page on one of them loads every resource, from any host. A site is a host ("example.com", which covers its subdomains) or an origin ("https://example.com", only that scheme, host and port). Replaces the profile's previous set; an empty one removes them all. Kept for this run only, so an app stores its own list and sets it at start. Incognito has its own set. Call on the main thread.
      Returns:
      false, and nothing changed, if an entry is neither a host nor an origin.
    • setProxyErrorListener

      public void setProxyErrorListener(CefriumProfile.ProxyErrorListener listener)
      Tells listener about every request of this profile's browsers that fails because of the proxy (the proxy cannot be reached, refuses the connection, asks for credentials, ...), so an app can tell its user that Tor or the VPN is down. Requests that fail this way are not retried without the proxy. Incognito browsers report to incognito()'s listener. Pass null to stop.
    • getDownloads

      public void getDownloads(CefriumProfile.DownloadsCallback callback)
      Every download of this profile, newest last, including the downloads of earlier runs of a persistent profile. Call on the UI thread.
    • setDownloadObserver

      public boolean setDownloadObserver(CefriumProfile.DownloadObserver observer)
      Reports every change to a download of this profile, whichever browser started it and whether or not that browser is still open: a download resumed after a restart has none. Pass null to stop. Call on the UI thread.
      Returns:
      false if the profile is not available (incognito before any private browser exists).
    • getCookieManager

      @CefriumExperimental public CefriumCookieManager getCookieManager()
      The cookies of this profile. See CefriumCookieManager.
    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object
    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object