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.
Shared instructions: shared-instructions.md — read first.
Working directory: before any project read or command, execute
native-artifact-compatibility.md Step 0.
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
and native controls. 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
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>'
Unknown/missing records block native mutation. Do not install packages, edit
native config, or run local native builds. Match the installed public README,
exports, and types to the resolved inventory before generating any wrapper.
Use @microsoft/power-apps-native-controls/geolocation only when that aggregate
is included in the verified release. Use the legacy
@microsoft/power-apps-native-bglocation import only when the matching leaf
is actually included. 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 for a resolved release that contains the aggregate:
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 resolved release instead supports expo-location, use its installed
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.
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.
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:
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
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
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: 196k | 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: 193k | 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: 193k | 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: 193k | Updated | Claude CodeCodex | Verified | Install |