microsoft/power-platform-skills / plugins/mobile-apps/skills/add-native/add-geolocation
add-geolocation
VerifiedInternal helper for one-shot coordinates or continuous/background GPS using release-matched geolocation controls; tracking adds durable storage and Dataverse sync.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 10.8 KB |
SKILL.md
View on GitHub---
name: add-geolocation
description: Internal helper for one-shot coordinates or continuous/background GPS using release-matched geolocation controls; tracking adds durable storage and Dataverse sync.
user-invocable: false
disable-model-invocation: true
allowed-tools: Read, Edit, Write, Grep, Glob, Bash, AskUserQuestion
model: sonnet
---
**Shared instructions: [shared-instructions.md](${PLUGIN_ROOT}/shared/shared-instructions.md)** — read first.
**Working directory:** before any project read or command, execute
[native-artifact-compatibility.md Step 0](${PLUGIN_ROOT}/shared/references/native-artifact-compatibility.md#0-bind-every-operation-to-the-app-root).
Inherit `/add-native`'s resolved absolute `working_dir`; bind every shell call and
file tool to it, even when this helper starts from another directory.
# Add Geolocation
Internal helper for `/add-native location` (one-shot), `/add-native geolocation`,
`/add-native location-tracking`, and `/add-native background-location` (tracking).
Preserve the requested mode; ask once if intent is unclear.
Read [release lifecycle](../../../shared/references/mobile-release-lifecycle.md)
and [native controls](../references/native-controls.md). Do not use
`GeolocationExtension`, HostingSDK, PCF, Launch URI, or Cordova bridge paths.
Do not substitute another library's `configureSync` / `HttpSyncContract` API.
## 1. Verify the app and resolved release
```bash
cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
test -f app.config.js && test -f power.config.json && test -f package.json && test -d src || { echo "BLOCKED: working_dir is not an initialized app" >&2; exit 1; }
node "${PLUGIN_ROOT}/scripts/resolve-mobile-release.js" --project-root '<working_dir>' --local-development
```
Follow the lifecycle's local-development policy for unverified context. Do not install packages, edit
native config, or run local native builds. Apply the native-controls
import-selection rules to the strict/local context, using the installed public
README, exports and types. Select `@microsoft/power-apps-native-controls/geolocation`
or the matching legacy `@microsoft/power-apps-native-bglocation` leaf under those rules.
Pick one literal import at generation time, never both.
The public runtime exports are `BgLocationClient`, `geoService`, `AuthMethod`,
and `ConnectionType`. Controls 0.2.0 uses background-location 0.2.3; do not copy
APIs from a newer leaf. Package facts are not evidence of a released player/base.
## 2. One-shot location — no tracking setup
Before writing or reusing the one-shot artifact, execute the shared
native-artifact compatibility contract's Steps 1-3 for the approved request.
Inspect the actual requested location API, platform/error behavior and consumers;
reuse a compatible wrapper or make only the approved scoped change. Do not turn
an approved one-shot request into tracking, Dataverse setup or screen integration.
For a single coordinate read, write `src/native/location.ts`. This path needs
**no `app_id`, data source, target table, or `startTracking`**. Skip Steps 3–5.
Check the selected version's location permission requirements; native binary
inclusion, OS declarations, runtime grants, and use are distinct.
Conditional example when the import-selection rules select the aggregate:
```ts
import { Platform } from 'react-native';
export async function getCurrentLocation() {
if (Platform.OS !== 'ios' && Platform.OS !== 'android') {
return { ok: false as const, reason: 'UNSUPPORTED_PLATFORM' as const };
}
try {
const { BgLocationClient } =
await import('@microsoft/power-apps-native-controls/geolocation');
const value = await new BgLocationClient().getCurrentLocation();
return { ok: true as const, value };
} catch {
return { ok: false as const, reason: 'LOCATION_FAILED' as const };
}
}
```
Refine permission/error results only from the installed public contract. Do not
guess fields or classify errors by matching arbitrary native error text. Screens
show an appropriate denied/unsupported/failure state without exposing raw errors.
If the capability gate instead selects installed `expo-location`, use its
one-shot contract with the same platform and result guards, not tracking setup.
## 3. Continuous tracking — permissions and ownership first
For background-location **0.2.3**, `startTracking` uses background permissions
even with `trackInBackground: false`. Do not promise foreground-only tracking
permissions. Missing OS declarations require another verified base, not a
runtime fallback or per-customer wrapping option.
Tracking is shared. `stopTracking()` and `isTracking()` have no `app_id`
parameter. Before code generation, record a single app-level tracking owner,
explicit user start/stop actions, and how other screens observe status.
Do not start duplicate sessions, reconfigure an already owned session, or stop
tracking on an unrelated screen's unmount. A JS ownership flag does not prove
ownership of a native session surviving a JS restart; reconcile native status
through the installed API before starting/stopping.
Use MSAL only; do not expose OneAuth or an auth selector. Read the installed
`geoService(dataSource, app_id)` contract, `AuthMethod.MSAL`,
`ConnectionType.Dataverse`, permissions, and persistence behavior. The tracking
target must include `connectionUrl`, `trackInBackground`, and
`persistAcrossRestarts` as required by that version. Optional interval,
distance, and notification settings must come from its types, not guesses.
## 4. Verify the tracking Dataverse target
This check is **tracking-only**, never a prerequisite for a one-shot read.
Use the package's default entity set `msdyn_locationrecords` and default field
map. Do not invent a custom table, create the table, or route missing-table
provisioning through `/add-dataverse`.
```bash
cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
ENV_JSON=$(node "${PLUGIN_ROOT}/scripts/resolve-environment.js" "$(node -e "console.log(require('./power.config.json').environmentId)")")
ENV_URL=$(node -e "const j=JSON.parse(process.argv[1]); process.stdout.write(j.environmentUrl || '')" "$ENV_JSON")
node "${PLUGIN_ROOT}/scripts/dataverse-request.js" "$ENV_URL" GET \
"EntityDefinitions?\$filter=EntitySetName eq 'msdyn_locationrecords'&\$select=LogicalName,EntitySetName"
```
- One row: capture its logical name and check the mapped columns below.
- Empty `value: []`: `BLOCKED (target table missing)`. Ask for the supported
geolocation table provisioning/setup mechanism, then re-run this workflow.
- Auth/environment failure: `UNVERIFIED (target table not checked)`. Stop.
```bash
cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
node "${PLUGIN_ROOT}/scripts/dataverse-request.js" "$ENV_URL" GET \
"EntityDefinitions(LogicalName='<logicalName>')/Attributes?\$select=LogicalName,AttributeType"
```
Confirm the installed README's default `fieldMap` columns and their types:
```text
msdyn_locationrecordid, msdyn_appid, msdyn_latitude, msdyn_longitude,
msdyn_altitude, msdyn_accuracy, msdyn_heading, msdyn_speed, msdyn_timestamp
```
Missing active columns block tracking. Do not report the target as ready or
silently substitute another table.
## 4a. Reconcile requested tracking artifacts
Read and execute [native-artifact-compatibility.md](${PLUGIN_ROOT}/shared/references/native-artifact-compatibility.md)
Steps 1–3 for the geolocation row before any writes or reuse. Inherit the current
approval/mode from `/add-native`; do not repeat a valid scoped approval.
Inspect `src/native/geolocation.ts` for all requested tracking/status/location
exports, `GeoTrackingTarget`, MSAL-only `geoService`/`BgLocationClient`, required
`connectionUrl`/`trackInBackground`/`persistAcrossRestarts`, durable storage, and
Dataverse sync. Reuse Step 4's verified `msdyn_locationrecords` columns; one-shot
location or a wrapper targeting another table is not compatible. An incompatible
artifact outside approval returns `NEEDS_CONTEXT` to the owner, or asks standalone;
missing table/columns remain `BLOCKED`, never a usable-control success.
## 5. Write the tracking wrapper from installed docs/types
Apply Step 4a's decision for `src/native/geolocation.ts`: create when requested
and missing, reuse unchanged only if compatible, or make only the approved scoped
update. Preserve custom code, exports, and callers; do not overwrite from the
example. Screens import this wrapper, not the package directly.
Only write the approved `src/native/geolocation.ts` changes after the preceding
gates pass. Screens import the wrapper, not the control. Require a native platform guard
before lazy imports inside `try`/`catch`; return discriminated results and never
throw. Preserve native capture, durable pending storage, and native upload
without depending on JavaScript being alive. Do not replace native behavior
with JS timers, upload loops, or a made-up adapter contract.
Use only verified public methods from the installed version. Keep
`geoService(dataSource, app_id)` initialization and the shared tracking owner
together; do not synthesize `stopTracking(app_id)` or `isTracking(app_id)`.
Do not add data sources or tracking side effects to the one-shot wrapper.
## 5a. Tracking integration guidance
Integration guidance for the owner; do not edit screens in this helper. Preserve the installed version's `GeoTrackingTarget` and requested tracking/status/location exports. Screens pass `connectionUrl`, `trackInBackground`, and `persistAcrossRestarts`; do not add `tableName` or `fieldMap` because this control owns its default table/mapping. Use only optional interval/distance/notification properties supported by the installed types. Do not restore an unconditional top-level native import or copy an unverified tracking implementation across package versions.
## 6. Validate and summarize
```bash
cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
npx --no-install tsc --noEmit
```
Execute the shared compatibility contract's Step 4 after type-checking. Recheck
all requested tracking APIs/flags, MSAL auth, durable storage/sync, and failure
paths. Type-check success alone is insufficient; do not fix screen/generated
files. Only after the requested artifact contract, table + columns, and
TypeScript all pass, return the shared compatibility result and actual
created/updated/reused paths before reporting:
Report the mode, resolved release/package version, wrapper path, permission
requirements, ownership decision for tracking, and whether native device
validation was performed. Tracking additionally requires verified table and
columns. Type-check success alone never means native execution is validated.
Update `memory-bank.md` only with completed wrapper work and explicit remaining
limitations. On any failed prerequisite, report `BLOCKED` / `UNVERIFIED`, not
`READY`; do not claim packages, players, or bases are available without evidence.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |